Proactively mint an errand for a user you already authenticated.

POST

/errand

curl --request POST \
  --url https://native-api.sudomimus.com/errand \
  --header 'Content-Type: application/json' \
  --data '{ "accessToken": "example" }'

• Production

Creates a browser handoff that lets an already authenticated user complete profile data or manage optional claim sharing. Supply a current application access token. The browser flow re-authenticates the user before making changes. If nothing is required, errand is null; otherwise open errand.url and optionally poll its status.

Request Body^required

Media typeapplication/json

object

accessToken

required

A current application access token (JWT) for the user. The token must be unexpired and its session must remain active.

string

Example^generated

{
  "accessToken": "example"
}

Responses

200

Either the errand handoff to open, or errand: null when nothing is owed. claims always reports the per-claim state.

Media typeapplication/json

object

errand

required

One of:

object

The browser side-trip that unblocks a claim-gated direct-issue: a short-lived, single-use bearer URL where the user authenticates when required, completes missing data, and manages consent. Open the URL and let the browser page guide the user.

object

errandKey

required

Bearer key (ernd_…); also the status-poll path key.

string

url

required

Open this in the user’s system browser.

string format: uri

expiresAt

required

string format: date-time

null

null

claims

required

Per-claim view across the five shareable claims, carried on both the 200 (why is a claim absent from the minted token) and the claim-gate 403 (what is still owed).

object

email

required

One shareable claim: what the application requests (requirement) joined with the user’s standing decision (state). UNKNOWN means the user was never asked; DENIED means the user explicitly declined.

object

requirement

required

The developer’s policy for the claim. SYNTHETIC_ONLY always emits the generated placeholder and never asks for real data. SYNTHETIC_FALLBACK guarantees the claim is present but uses a generated placeholder (a stand-in name, a proxy email, or a generated avatar) when the user has not shared real data. Unlike REQUIRED, neither synthetic mode blocks issuance or raises an errand.

string

Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK

state

required

string

Allowed values: UNKNOWN GRANTED DENIED

firstName

required

One shareable claim: what the application requests (requirement) joined with the user’s standing decision (state). UNKNOWN means the user was never asked; DENIED means the user explicitly declined.

object

requirement

required

The developer’s policy for the claim. SYNTHETIC_ONLY always emits the generated placeholder and never asks for real data. SYNTHETIC_FALLBACK guarantees the claim is present but uses a generated placeholder (a stand-in name, a proxy email, or a generated avatar) when the user has not shared real data. Unlike REQUIRED, neither synthetic mode blocks issuance or raises an errand.

string

Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK

state

required

string

Allowed values: UNKNOWN GRANTED DENIED

lastName

required

One shareable claim: what the application requests (requirement) joined with the user’s standing decision (state). UNKNOWN means the user was never asked; DENIED means the user explicitly declined.

object

requirement

required

The developer’s policy for the claim. SYNTHETIC_ONLY always emits the generated placeholder and never asks for real data. SYNTHETIC_FALLBACK guarantees the claim is present but uses a generated placeholder (a stand-in name, a proxy email, or a generated avatar) when the user has not shared real data. Unlike REQUIRED, neither synthetic mode blocks issuance or raises an errand.

string

Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK

state

required

string

Allowed values: UNKNOWN GRANTED DENIED

staticAvatar

required

One shareable claim: what the application requests (requirement) joined with the user’s standing decision (state). UNKNOWN means the user was never asked; DENIED means the user explicitly declined.

object

requirement

required

The developer’s policy for the claim. SYNTHETIC_ONLY always emits the generated placeholder and never asks for real data. SYNTHETIC_FALLBACK guarantees the claim is present but uses a generated placeholder (a stand-in name, a proxy email, or a generated avatar) when the user has not shared real data. Unlike REQUIRED, neither synthetic mode blocks issuance or raises an errand.

string

Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK

state

required

string

Allowed values: UNKNOWN GRANTED DENIED

animatedAvatar

required

One shareable claim: what the application requests (requirement) joined with the user’s standing decision (state). UNKNOWN means the user was never asked; DENIED means the user explicitly declined.

object

requirement

required

The developer’s policy for the claim. SYNTHETIC_ONLY always emits the generated placeholder and never asks for real data. SYNTHETIC_FALLBACK guarantees the claim is present but uses a generated placeholder (a stand-in name, a proxy email, or a generated avatar) when the user has not shared real data. Unlike REQUIRED, neither synthetic mode blocks issuance or raises an errand.

string

Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK

state

required

string

Allowed values: UNKNOWN GRANTED DENIED

Example

{
  "claims": {
    "email": {
      "requirement": "SYNTHETIC_ONLY",
      "state": "UNKNOWN"
    },
    "firstName": {
      "requirement": "SYNTHETIC_ONLY",
      "state": "UNKNOWN"
    },
    "lastName": {
      "requirement": "SYNTHETIC_ONLY",
      "state": "UNKNOWN"
    },
    "staticAvatar": {
      "requirement": "SYNTHETIC_ONLY",
      "state": "UNKNOWN"
    },
    "animatedAvatar": {
      "requirement": "SYNTHETIC_ONLY",
      "state": "UNKNOWN"
    }
  }
}

Headers

Cache-Control

string

Allowed values: no-store

Prevent storage of the credential-bearing response.

Pragma

string

Allowed values: no-cache

Legacy cache instruction retained for credential responses.

401

The access token is missing, malformed, expired, or no longer active.

Media typeapplication/json

Error response body. Known failures may include a stable reason. Some failures are status-only and have an empty body. A missing, malformed, or structurally invalid JSON body returns InvalidBody.

object

reason

Stable machine-readable reason code.

string

Example^generated

{
  "reason": "example"
}

403

The application or the account is disabled.

Media typeapplication/json

Error response body. Known failures may include a stable reason. Some failures are status-only and have an empty body. A missing, malformed, or structurally invalid JSON body returns InvalidBody.

object

reason

Stable machine-readable reason code.

string

Example^generated

{
  "reason": "example"
}

default

Error response.

Media typeapplication/json

Error response body. Known failures may include a stable reason. Some failures are status-only and have an empty body. A missing, malformed, or structurally invalid JSON body returns InvalidBody.

object

reason

Stable machine-readable reason code.

string

Example^generated

{
  "reason": "example"
}