Skip to content
Hexel StudioDocs

Access tokens

What an access token is, how long it lasts, which organization it's for, what it contains and how it stops working.

On this page

Every call to the Hexel Studio API is made with an access token: a short-lived, signed token that names one identity in one organization. The token service at https://sts.hexelstudio.com issues them.

WhoHow they get an access token
A personThe console and other Hexel Studio apps get tokens for you when you sign in with your Hexel account. Hexel Studio doesn't issue personal tokens for use outside its apps.
A service userExchange an API key or OAuth client credentials at POST https://sts.hexelstudio.com/token, or send the API key in X-API-Key and let Hexel Studio exchange it for you. See Authenticate to the API.
A role sessionAssume a role with an access token, an API key or OAuth client credentials. See Roles.

Lifetimes

TokenLifetime
Access token for a person or a service user15 minutes. For a person, never later than the sign-in deadline (below).
Refresh token (people only)Single use: each refresh returns a new one. The chain of refresh tokens lasts at most 30 days from when the first one was issued, and never past the sign-in deadline.
Role session1 hour by default, or the role's maximum session duration if that is shorter. You can ask for a shorter or longer duration up to the role's maximum, which is at most 12 hours.

expires_in in a token response is the remaining lifetime in seconds.

Token response for a service user
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "refresh_token": "",
  "token_type": "Bearer",
  "expires_in": 900
}

Service users and role sessions get no refresh token. When the access token expires, exchange the credential again. Reuse a token until shortly before it expires rather than requesting one per call: the token service issues at most 60 tokens per minute for one credential (see Limits).

The sign-in deadline

When you sign in with your Hexel account, that sign-in has a deadline. Tokens issued from it never outlive it: each access token expires at the deadline if that comes before its 15 minutes, and refreshing stops working once the deadline passes. You then sign in again, even if 30 days haven't passed.

What refresh checks

A Hexel Studio app refreshes a person's token without asking you to sign in again, but only while all of these hold:

  • Your account is active and its email address is verified.
  • You're still an active member of the token's organization, and the organization is active.
  • Your refresh tokens haven't been revoked (see Revocation).

One organization per token

An access token is for exactly one organization, shown in its org claim. Everything you do with it happens in that organization.

  • A token can't be moved to another organization. Refreshing keeps the organization; to work in another organization, an app gets a new token for it. In the console, that's what switching organizations does.
  • A service user's token is always for the service user's organization.
  • If you send X-Organization-Id with a request, it must equal the token's organization, or the request is refused.

What's in a token

Access tokens are JSON Web Tokens signed with RS256. You can verify one with the keys at https://sts.hexelstudio.com/.well-known/jwks.json; pick the key by the token's kid header.

You can rely on these claims:

ClaimMeaning
isshttps://sts.hexelstudio.com
aud["https://api.hexelstudio.com"]
subThe identity: a user ID, a service user ID (su_...) or, in a role session, the role ID
typuser, service or role
orgThe organization ID
iat, expIssued at and expires at, in seconds since the epoch
jtiA unique token ID
sidThe session the token belongs to
cidService users only: the API key ID or OAuth client ID the token was issued from
auth_time, session_expires_atPeople only, when present: when you signed in and the sign-in deadline

A role session token also carries:

ClaimMeaning
roleThe role ID
rsnThe session name
srcWho originally signed in: type, id and org
actWho assumed the role, as a chain when a role session assumed another role
scopeThe role's workspace and environment limit (ws, env), when the role has one

Tokens can carry other claims. Don't rely on them.

A token carries no permissions, roles or workspace. Hexel Studio looks permissions up for every request, so a change to a policy applies to tokens that already exist, without a new token. Permission checks are cached briefly, so a change can take up to about a minute to reach every service.

Revocation

What happensEffect on tokens
You sign out of a Hexel Studio appThe app revokes its refresh token. Revoking one refresh token of an account revokes all of that account's refresh tokens, so no app or device can renew an access token with them. Access tokens already issued keep working until they expire, at most 15 minutes.
An API key or OAuth client is revokedAccess tokens issued from it are refused. A revoked key sent in X-API-Key stops working at once, and in any case within 60 seconds.
A service user is deactivated or deletedAll of its tokens are refused.
A role's sessions are revokedRole sessions issued before that moment are refused.
A member is removed from the organizationTheir tokens for that organization can't be refreshed.

The identity and access API applies the refusals above within about a minute of the change. Other Hexel Studio APIs may accept such a token until it expires, at most 15 minutes for an access token, or the session's end for a role session.