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. A missing, unknown, revoked or expired key answers 401. A valid key without the scope an operation needs answers 403.

Path Parameters

​
account_id
string
required

The account_id the workspace sends with its assessments, as one path segment (percent-encode '|' and ':' if the client requires it). A value that does not match the account_id shape answers 400 invalid_request. The provider's own opaque identifier for the account being checked, scoped to the calling workspace. It must be provider-opaque and must not contain a direct identifier (email, phone, name, national id): that is a provider obligation the schema can only partly check. '|' is accepted so an Auth0 user id such as 'auth0|64abc' passes unchanged; '@', '+', '$' and whitespace are refused by the pattern, as is an exact-shape JWT; a hex digest such as a SHA-256 is allowed, because hashing an internal id is a common pseudonymous scheme. A value such as '07700900123' or 'jane.doe.gmail.com' cannot be told apart from an opaque id. It travels in bodies, and in a URL only as the path segment of GET /v1/accounts/{account_id} and its /assessments. An assessment requested by a provider hook at pre_registration, which has no account yet, carries the server-issued account_id pre: followed by its assessment_id.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:|-]{0,127}$

Body

application/json

POST /v1/accounts/{account_id}/enforcements body: what the workspace did to the account in its identity provider after reading the account's risk at risk_version. The account is named by the path and the workspace by the API key, so neither is a body member. An enforcement is the workspace's own action, not an outcome: what the workspace later learned about an assessment goes to POST /v1/assessments/{assessment_id}/outcomes. The record's key is (account, risk_version, flow, action), so a retry of the same report is safe and needs no Idempotency-Key.

​
risk_version
integer
required

The account's risk_version the workspace acted on, as read from GET /v1/accounts/{account_id}, GET /v1/accounts, an assessment answer or account.risk_changed. A version older than the account's current one is accepted and stored; a version newer than the current one answers 409 risk_version_ahead.

Required range: x >= 1
​
flow
enum<string>
required

The flow whose decision (decisions_by_flow) the workspace acted on.

Available options:
account_creation,
login,
purchase
​
action
enum<string>
required

What the workspace did in its identity provider: revoke_sessions (signed the account out everywhere), restrict (limited what the account can do), unrestrict (lifted an earlier restriction), fail_onboarding (stopped an account that was still onboarding), reject_activation (refused to activate a provisional account) or none (decided to take no action).

Available options:
revoke_sessions,
restrict,
unrestrict,
fail_onboarding,
reject_activation,
none
​
state_before
enum<string>
required

The account's state in the workspace's identity provider just before the action: onboarding, provisional (created, not yet activated), active, restricted or rejected.

Available options:
onboarding,
provisional,
active,
restricted,
rejected
​
status
enum<string>
required

applied when the identity provider accepted the action, failed when it refused it or could not be reached. Only applied counts as enforced.

Available options:
applied,
failed
​
provider
enum<string>
required

The identity provider the action ran in; custom for the workspace's own user store.

Available options:
clerk,
workos,
auth0,
custom
​
error_code
string

Why a failed action failed, as a short code of the workspace's choosing (lower-case letters, digits, '_', '.' and '-'), such as the identity provider's error code. Allowed only with status failed: with status applied it answers 400 invalid_request. Keep personal data out of it.

Required string length: 1 - 128
Pattern: ^[a-z0-9_.-]+$

Response

The enforcement was already recorded: the record as first stored. The report did not change it.

The answer of POST /v1/accounts/{account_id}/enforcements: one enforcement of one of the calling workspace's accounts, kept once per (account, risk_version, flow, action). The first report answers 201 with the new record. A repeat answers 200 with the record as first stored, whatever the repeat's state_before, status, provider or error_code. The one exception is a stored failed record followed by an applied report: the record becomes applied, keeps its id and created_at, takes the applied report's state_before and provider, drops error_code and answers 201, so a successful retry after a failure is recorded. Only an applied record at the account's current risk_version takes the account out of GET /v1/accounts?unenforced=true.

​
id
string
required

Opaque, server-assigned id of one recorded enforcement: 'enf_' and 26 Crockford base32 characters. Unique within the workspace.

Pattern: ^enf_[0-9A-HJKMNP-TV-Z]{26}$
​
account_id
string
required

The account_id of the request path.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:|-]{0,127}$
​
risk_version
integer
required

The account's risk_version the workspace acted on. It can be older than the account's current risk_version: such a record is kept and does not count for unenforced.

Required range: x >= 1
​
flow
enum<string>
required

The flow whose decision the workspace acted on.

Available options:
account_creation,
login,
purchase
​
action
enum<string>
required

What the workspace did in its identity provider: revoke_sessions (signed the account out everywhere), restrict (limited what the account can do), unrestrict (lifted an earlier restriction), fail_onboarding (stopped an account that was still onboarding), reject_activation (refused to activate a provisional account) or none (decided to take no action).

Available options:
revoke_sessions,
restrict,
unrestrict,
fail_onboarding,
reject_activation,
none
​
state_before
enum<string>
required

The account's state in the workspace's identity provider just before the action: onboarding, provisional (created, not yet activated), active, restricted or rejected.

Available options:
onboarding,
provisional,
active,
restricted,
rejected
​
status
enum<string>
required

applied when the identity provider accepted the action, failed when it refused it or could not be reached. Only applied counts as enforced.

Available options:
applied,
failed
​
provider
enum<string>
required

The identity provider the action ran in; custom for the workspace's own user store.

Available options:
clerk,
workos,
auth0,
custom
​
created_at
string<date-time>
required

When NoResponse first recorded this enforcement, in UTC. A failed record that becomes applied keeps it.

​
error_code
string

Why a failed action failed, as a short code of the workspace's choosing (lower-case letters, digits, '_', '.' and '-'), such as the identity provider's error code. Allowed only with status failed: with status applied it answers 400 invalid_request. Keep personal data out of it.

Required string length: 1 - 128
Pattern: ^[a-z0-9_.-]+$