Skip to content

How Personal Tokens Work

This page explains how Personal Access Tokens (PATs) work in Qualytics — from generation and authentication to expiration, lifecycle management, and security.

Token Generation

When you generate a Personal Access Token, the platform creates a signed JWT (JSON Web Token). The token contains claims that identify you (user ID, email, name) along with metadata like the creation timestamp and expiration date.

The token is returned to you only once at creation time. Internally, the platform stores a one-way hash of the token — the plaintext value is never persisted. This means if you lose the token, it cannot be retrieved and you must generate a new one.

Info

For step-by-step instructions on generating a token, see the Generate Personal Token page.

Authentication Flow

When you include a Personal Access Token in an API request, the platform validates it through the following steps:

  1. Extract — The token is extracted from the Authorization: Bearer <token> header.
  2. Decode — The JWT signature is verified and claims are decoded.
  3. Validate — The issuer, user ID, and expiration are checked.
  4. Revocation check — The token's hash is compared against the stored hash in the database to confirm it is still active (not revoked).
  5. Access granted — The request proceeds with the permissions of the token's owner.

The platform also tracks when the token was last used, updating the Last Used timestamp on each successful authentication.

Token Properties

Each Personal Access Token displays the following properties in the token list:

token-properties-annotated

REF. Property Description
1 Icon A key icon with a colored background indicating the token's state: green (Active), orange (Revoked), or red (Expired).
2 Name A user-defined label to identify the token. Must be unique per user — creating a token with a duplicate name returns a 409 Conflict error.
3 Expiration The date and time when the token becomes invalid, shown as relative time. Hover to see the exact date. See Expiration Options below.
4 Last Used The timestamp of the last successful API request made with this token, shown as relative time. Hover to see the exact date.
5 Status Badge The current state of the token: Active (green), Revoked (orange), or Expired (red).

Expiration Options

Tokens include an expiration period that defines how long they remain valid. When a token reaches its expiration date, it automatically stops working and must be regenerated.

No. Expiration
1. 30 Days
2. 60 Days
3. 90 Days
4. 1 Year
5. Never

Choosing a time-bound expiration helps maintain security and ensures unused tokens do not stay active indefinitely.

Warning

Avoid using the Never expiration option, as tokens that never expire can create security risks.

Token States

Each token exists in one of three states, visually represented by a colored badge and icon:

State Color Description
Active Green The token is valid and can be used for API authentication.
Revoked Orange The token has been explicitly deactivated by the user or admin. API requests are rejected.
Expired Red The token's expiration date has passed. API requests are rejected automatically. 
stateDiagram-v2
    [*] --> Active: Generate
    Active --> Revoked: Revoke
    Active --> Expired: Expiration date reached
    Revoked --> Active: Restore
    Revoked --> [*]: Delete
    Expired --> [*]: Delete

Each state determines which actions are available:

State Available Actions
Active Revoke
Revoked Restore, Delete
Expired (not yet revoked) Revoke
Expired (already revoked) Delete

Note

A token can expire without being revoked — in this case, the UI shows Revoke as the available action. Once revoked, an expired token can only be deleted. The UI hides the Restore option for expired tokens.

Token Usage Tracking

The platform tracks when each token was last used for an API request. The Last Used timestamp is updated on each successful authentication.

This tracking helps you:

  • Identify tokens that are actively in use.
  • Find unused tokens that may need to be revoked.
  • Audit when automated systems last communicated with the API.

Info

For details on how usage status is displayed in the interface, see the List Columns page.

SCIM Administration Token

SCIM (System for Cross-domain Identity Management) is a standard for automating user provisioning between identity providers and applications.

The SCIM Administration Token option restricts a token to SCIM-related operations only, such as user provisioning and identity management. When this option is enabled, the token cannot be used to access any other API endpoints.

Only users with the Admin role can create SCIM Administration Tokens.

Security Considerations

Info

For comprehensive security guidelines — including token storage, rotation, expiration strategy, and when to use Personal vs Service Tokens — see the Best Practices page.