Exchange an access-key credential for application tokens.

POST

/direct-issue/access-key

curl --request POST \
  --url https://native-api.sudomimus.com/direct-issue/access-key \
  --header 'Content-Type: application/json' \
  --data '{ "applicationAnchor": "example", "accessKeyIdentifier": "example", "accessKeySecret": "example" }'

• Production

Exchanges an application-scoped access-key identifier and secret for access and refresh tokens. The key must belong to the named application, remain active, and satisfy its configured authorization rules. Credential rejection uses the single opaque reason AccessKeyDirectDenied.

Request Body^required

Media typeapplication/json

object

applicationAnchor

required

Public anchor identifying the integrating application.

string

accessKeyIdentifier

required

Canonical access-key identifier, including the mandatory acs_k_ prefix followed by its UUID.

string

/^acs_k_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/

accessKeySecret

required

Canonical access-key secret, including the mandatory acs_t_ prefix followed by 64 lowercase hexadecimal characters (32 random bytes). Returned only when the access key is issued.

string

/^acs_t_[0-9a-f]{64}$/

Example^generated

{
  "applicationAnchor": "example",
  "accessKeyIdentifier": "example",
  "accessKeySecret": "example"
}

Responses

200

Tokens issued.

Media typeapplication/json

object

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

applicationAnchor

required

string

accessToken

required

Short-lived access token (JWT). Payload sub is the pairwise sector subject, sid identifies the session, and jti identifies this token instance. It contains no profile claims or raw account identifier; use Session API /userinfo for current shared identity data.

string

refreshToken

required

Long-lived refresh token JWT with stable payload sid, version identifier jti, and positive rotationVersion. It contains no user identifier. Use Session API /refresh for renewal without re-presenting the access key.

string

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.

400

Malformed request body. The reason distinguishes InvalidAccessKeyIdentifier (must use the canonical acs_k_<UUID v4> form) and InvalidAccessKeySecret (must use the canonical acs_t_<64 lowercase hex chars> form).

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"
}

401

Reason AccessKeyDirectDenied: the access-key credential was rejected. Obtain a current credential before retrying.

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 attempt was refused. The response reason distinguishes:

• Layer1Denied, Layer2Denied, Layer3Denied — application policy rejected the attempt.
• ApplicationNotActive — the application is unavailable.
• AccountDisabled or AccountDeleted — the account is unavailable for issuance.
• EmailDomainBlocked, EmailDomainRequiresSso, or SsoAuthorityConflict — email-domain policy prevents issuance.
• ClaimConsentRequired or RequiredClaimDataMissing — browser interaction is required before direct issuance can continue.

Claim-gate responses also include claims and an errand browser handoff. Open errand.url, wait or poll its status, then retry this request once after completion.

Media typeapplication/json

403 body. For the claim-gate reasons (ClaimConsentRequired, RequiredClaimDataMissing) the claims view and the errand handoff are present; for every other reason only reason is set.

object

reason

required

Stable machine-readable reason code.

string

claims

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

errand

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

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.

404

Application anchor not found.

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"
}

409

Reason AuthorizationArtifactStale: identity authority changed during the attempt. Retry the complete credential exchange.

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"
}

429

Too many access-key attempts. Back off before retrying.

500

Access-key issuance failed with an empty response body.

503

Access-key issuance is temporarily unavailable.

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"
}