Sessions and tokens
A sign-in starts a session. Your app holds two tokens for it: one that proves who the user is right now, and one that keeps them signed in without asking for the password again.
The two tokens
| Access token | Refresh token | |
|---|---|---|
| What it is for | Sent with every request to prove who the user is | Exchanged for a new access token when the old one expires |
| Lifetime | 15 minutes | 30 days |
| Format | Signed JWT your servers can verify | Opaque random string |
| Where to keep it | Memory, or a secure cookie | Server side, or an HttpOnly cookie. Never in local storage |
| Can be reused | Yes, until it expires | No. Each refresh returns a new one and retires the old one |
What's inside an access token
substring- The user’s ID.
tidstring- Your workspace ID.
sidstring- The session ID. Every token from the same sign-in shares it.
rolesstring[]- The user’s roles, including custom roles you created.
expnumber- When the token expires, in seconds since 1970.
custom claimsany- Anything your post-login actions added.
Verify a token on your server
Access tokens are signed with RS256. Fetch the public keys from your JWKS endpoint, cache them, and check the signature and exp on every request. Most JWT libraries do this for you.
GET https://id.trustportidentity.com/.well-known/jwks.jsonKeep someone signed in
When an access token expires, swap the refresh token for a fresh pair:
curl -X POST https://id.trustportidentity.com/api/v1/auth/refresh \
-H "Content-Type: application/json" \
-d '{ "refresh_token": "9f2c…" }'Each refresh checks the account again. If the user has been deactivated or deleted in the meantime, the refresh fails and they must sign in again. Role changes show up in the next access token.
Sign people out
| You want to… | Do this |
|---|---|
| Sign the current user out of this device | POST /api/v1/auth/logout with their access token |
| Sign yourself out everywhere | Account & Security › Sessions › Sign out everywhere, or POST /api/v1/auth/sessions/revoke-all |
| Sign someone else out everywhere and keep them out | Users › Lock account. Their sessions end straight away |
Your own sessions
If you think someone else has used your account, choose Sign out everywhere, change your password and check your two-factor devices.