Skip to content
NovaVMS Manual

API keys

Service-account API keys are the credential type for server-to-server integrations. Each key belongs to a service account, carries a fixed role and scope, and does not expire unless you set expires_at. Issuing and revoking keys is an admin-and-owner-only operation (D81 / D83) — operators cannot manage key material. If you only need to mint a key, see Rotate an API key for the admin UI flow; this page covers what you need to know as the developer consuming the key.

Key prefixes

Every key starts with a prefix that tells you which environment it belongs to:

PrefixEnvironmentBehaviour
sk_live_Production orgHits real cameras, real events, real billing
sk_test_Sandbox orgReturns canned data for most read endpoints; writes are accepted but do not propagate to gateways

The prefix is the first 8 characters including the underscore (sk_live_, sk_test_). Never log or expose the full key; logging the prefix is fine.

Create a key

Use the admin UI at /admin/service-accounts — key creation is not available over the API in v1 by design (issuing governance credentials from a machine-callable endpoint is a standing audit finding). The full UI flow is documented in Rotate an API key. The key is shown exactly once in a modal; copy it into your secret store immediately (since v1.0).

List keys you can see

A service account can list its own keys (prefix only — never the full value) at GET /api/v1/service-accounts/{id}/keys:

Terminal window
curl -H "Authorization: Bearer sk_live_abc123" \
  "https://novavms.novalien.com/api/v1/service-accounts/a1b2c3d4-1234-5678-9abc-def012345678/keys"
// @novavms/sdk >= 1.0.0
const keys = await novavms.serviceAccounts.listKeys('a1b2c3d4-1234-5678-9abc-def012345678');
# novavms >= 1.0.0
keys = novavms.service_accounts.list_keys("a1b2c3d4-1234-5678-9abc-def012345678")

Expected response:

{
  "keys": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "prefix": "sk_live_",
      "name": "Slack SOC bridge",
      "created_at": "2026-03-01T10:00:00Z",
      "last_used_at": "2026-04-21T13:59:42Z",
      "expires_at": null
    }
  ]
}

Rotate a key

The rolling-cutover pattern: create a second key with the same scope, push it to the integration, wait for last_used_at to advance on the new key, then revoke the old one. Full procedure in the admin UI: Rotate an API key.

Revoke a key

DELETE /api/v1/service-accounts/{id}/keys/{key_id} — instant and irreversible (since v1.0):

Terminal window
curl -X DELETE -H "Authorization: Bearer sk_live_abc123" \
  "https://novavms.novalien.com/api/v1/service-accounts/a1b2c3d4-1234-5678-9abc-def012345678/keys/3fa85f64-5717-4562-b3fc-2c963f66afa6"
await novavms.serviceAccounts.revokeKey(
  'a1b2c3d4-1234-5678-9abc-def012345678',
  '3fa85f64-5717-4562-b3fc-2c963f66afa6',
);
novavms.service_accounts.revoke_key(
    "a1b2c3d4-1234-5678-9abc-def012345678",
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
)

The next request signed with the revoked key returns 401 UNAUTHORIZED. The audit log records service_account.key_revoked with the actor user_id and the key prefix.

Per-key quota

Each key shares the org’s rate-limit bucket by default (1000 req/min, 100 burst). A per-key override can be set from the admin UI if one integration must not starve another — see Rate limits.