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.

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 pairwise sub with a fresh jti.

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.

Some unrecoverable rotation conflicts return an empty 401 body.

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