Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

Your API key, sent as Authorization: Bearer <key>. A key is nrk_live_ or nrk_test_, a 26-character key id, _ and a 43-character secret. A key sees only its own environment's data.

Each key has one or more scopes: assess creates and reads assessments, records outcomes and reports key usage; history reads assessments, an account's current risk, the accounts whose risk changed and an account's history, records enforcements and erases an account; detailed adds the detailed view; webhooks registers, tests, rotates and deletes webhook endpoints; integrations registers and manages hosted provider integrations; management creates, lists and revokes the keys of its own environment and reads and changes that environment's settings. A missing, unknown, revoked or expired key answers 401. A valid key without the scope an operation needs answers 403.

Path Parameters

workspace_id
string
required

The workspace id. A workspace the acting user is not an active member of answers 404, as do another workspace than an API key's own, a malformed id and a test environment's id. The workspace id, which is also its live environment's workspace id; the test environment's is the same id with:test appended. A workspace created through the API is tnt_ and a 26-character ULID.

Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]{0,122}$

Body

application/json

POST /v1/workspaces/{workspace_id}/keys body. Creates an API key in one environment of the workspace with the scopes named, and returns its secret once. A live key needs the admin or owner role; a test key needs developer or above. An API key with the management scope creates keys in its own environment with scopes it holds itself. Each scope may appear once.

environment
enum<string>
required

The environment the key belongs to. A live key assesses with live sources; a test key answers from the deterministic simulator.

Available options:
live,
test
scopes
enum<string>[]
required

The key's scopes, each at most once.

Required array length: 1 - 7 elements
Available options:
assess,
history,
delete,
webhooks,
detailed,
integrations,
management

Response

The key and its secret, shown here once only.

One API key of a workspace, as the console shows it. A key belongs to exactly one environment. Every other field is safe to show.

id
string
required

The key's public id, a 26-character ULID.

Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
workspace_id
string
required

The workspace id, which is also its live environment's workspace id; the test environment's is the same id with:test appended. A workspace created through the API is tnt_ and a 26-character ULID.

Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]{0,122}$
environment
enum<string>
required

The environment the key belongs to. A live key assesses with live sources; a test key answers from the deterministic simulator.

Available options:
live,
test
prefix
string
required

The public start of the credential, nrk__, which identifies the key in logs and secret stores without its secret.

Pattern: ^nrk_(live|test)_[0-7][0-9A-HJKMNP-TV-Z]{25}$
scopes
enum<string>[]
required

The key's scopes, each at most once.

Required array length: 1 - 7 elements
Available options:
assess,
history,
delete,
webhooks,
detailed,
integrations,
management
status
enum<string>
required

active: the key authenticates. expired: a rotation's overlap window has ended (expires_at). revoked: the key was revoked (revoked_at) and answers 401.

Available options:
active,
expired,
revoked
created_at
string<date-time>
required
created_by
string

The external user id of the member who created the key through the console, or the prefix (nrk__) of the management key that created it. Absent for a key NoResponse issued or a rotation made.

Required string length: 1 - 256
Pattern: ^[!-~]{1,256}$
expires_at
string<date-time>

When a rotated key stops authenticating (POST /v1/keys/rotate). Absent for a key with no end.

revoked_at
string<date-time>
revoked_by
string

The external user id of the member who revoked the key through the console, or the prefix of the management key that revoked it. Absent when the key is not revoked or NoResponse revoked it.

Required string length: 1 - 256
Pattern: ^[!-~]{1,256}$
key
string

The credential, nrk_. Present only in the 201 answer that created the key.

Pattern: ^nrk_(live|test)_[0-7][0-9A-HJKMNP-TV-Z]{25}_[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$