Skip to content
Sudomimus

Rotate a refresh token and issue a new access token.

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

Rotates an ordinary application refresh token and returns a new access token and refresh token. Replace the stored refresh token after every success. A near-simultaneous retry may receive the already-issued winning token pair. Reuse outside that allowance revokes the session; restart through an initial issuance flow. OIDC sessions must use the OIDC /token endpoint instead. Workload refresh tokens have the same actor-free wire shape; the authoritative session restores the Workload actor and emits a dedicated Workload access token on every rotation.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
refreshToken
required

Signed refresh credential carrying stable payload sid, exact version jti, and rotationVersion; it contains no user identifier.

string
Examplegenerated
{
  "refreshToken": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

New access and refresh tokens issued. A near-simultaneous retry may receive the token pair already issued for the same rotation.

Media typeapplication/json
object
claims
required
object
email
required
object
requirement
required
string
Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK
state
required
string
Allowed values: UNKNOWN GRANTED DENIED
firstName
required
object
requirement
required
string
Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK
state
required
string
Allowed values: UNKNOWN GRANTED DENIED
lastName
required
object
requirement
required
string
Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK
state
required
string
Allowed values: UNKNOWN GRANTED DENIED
staticAvatar
required
object
requirement
required
string
Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK
state
required
string
Allowed values: UNKNOWN GRANTED DENIED
animatedAvatar
required
object
requirement
required
string
Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK
state
required
string
Allowed values: UNKNOWN GRANTED DENIED
accessToken
required

Newly issued short-lived access token JWT carrying payload sid and owner Account pairwise sub with a fresh jti. A Workload-descended session uses media type vnd.sudomimus.workload-access+jwt and adds exact pairwise act: {sub}; an Account session uses vnd.sudomimus.application-access+jwt and has no act.

string
refreshToken
required

Newly issued refresh token JWT for the same payload sid, with a fresh jti and incremented rotationVersion; the presented version has been consumed.

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

Section titled “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

Section titled “400”

Reason AccountNotFound — the account behind the refresh token could not be resolved.

Media typeapplication/json

Error response body. A missing, malformed, or structurally invalid JSON request body returns InvalidBody. Documented status-only failures have an empty response body.

object
reason
required
string
message
string
Examplegenerated
{
  "reason": "example",
  "message": "example"
}

401

Section titled “401”

Refresh token rejected. The reason distinguishes:

  • RefreshTokenInvalid — the token is malformed or does not match a valid application session.
  • RefreshTokenInvalidType — the token type or issuance protocol is not accepted here.
  • RefreshTokenInvalidSignature — signature verification failed.
  • RefreshTokenSuspended — the session is suspended.
  • RefreshTokenExpired — the token is past its exp.
  • RefreshTokenRevoked — the session is revoked.
  • RefreshTokenFamilyCompromised — a stale token version was used; the session is now revoked.

A public reason uses the application/json body below. An unrecoverable rotation conflict whose classification is wire-private instead returns an empty 401 body and omits Content-Type; clients must inspect body presence before parsing JSON.

Media typeapplication/json

Error response body. A missing, malformed, or structurally invalid JSON request body returns InvalidBody. Documented status-only failures have an empty response body.

object
reason
required
string
message
string
Examplegenerated
{
  "reason": "example",
  "message": "example"
}

403

Section titled “403”

The attempt was refused. The reason distinguishes:

  • AccountDisabled or AccountDeleted — the account is unavailable for issuance.
  • ApplicationNotActive — the application is unavailable.
  • ClaimConsentRequired or RequiredClaimDataMissing — current claim requirements are not satisfied.
  • LegalAgreementRequired — the account must accept the current basic terms through a new browser sign-in before refresh.
  • EmailDomainBlocked, EmailDomainRequiresSso, or SsoAuthorityConflict — email-domain policy prevents issuance.
Media typeapplication/json

Error response body. A missing, malformed, or structurally invalid JSON request body returns InvalidBody. Documented status-only failures have an empty response body.

object
reason
required
string
message
string
Examplegenerated
{
  "reason": "example",
  "message": "example"
}

409

Section titled “409”

Reason AuthorizationArtifactStale: identity authority changed during refresh. Restart through an initial issuance flow.

Media typeapplication/json

Error response body. A missing, malformed, or structurally invalid JSON request body returns InvalidBody. Documented status-only failures have an empty response body.

object
reason
required
string
message
string
Examplegenerated
{
  "reason": "example",
  "message": "example"
}

default

Section titled “default”

Error response.

Media typeapplication/json

Error response body. A missing, malformed, or structurally invalid JSON request body returns InvalidBody. Documented status-only failures have an empty response body.

object
reason
required
string
message
string
Examplegenerated
{
  "reason": "example",
  "message": "example"
}