# How Personal Tokens Work

Source: https://userguide.qualytics.io/settings/access-tokens/personal-token/deep-dive/how-it-works/

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](https://userguide.qualytics.io/settings/access-tokens/personal-token/managing/generate-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](https://userguide.qualytics.io/assets/settings/access-tokens/personal-token/deep-dive/how-it-works/token-properties-annotated.png)

| 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](https://userguide.qualytics.io/settings/access-tokens/personal-token/deep-dive/how-it-works/#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** | Yes Green | The token is valid and can be used for API authentication. |
| **Revoked** | Amber | The token has been explicitly deactivated by the user or admin. API requests are rejected. |
| **Expired** | No Red | The token's expiration date has passed. API requests are rejected automatically. |

```mermaid
stateDiagram-v2
    [*] --> Active: Generate
    Active --> Revoked: Revoke
    Active --> Expired: Expiration date reached
    Revoked --> Active: Restore
    Revoked --> Expired: Expiration date reached
    Revoked --> [*]: Delete
    Expired --> [*]: Delete
```

Each state determines which actions are available:

| State | Available Actions |
| --- | --- |
| **Active** | [Revoke](https://userguide.qualytics.io/settings/access-tokens/personal-token/managing/revoke-token/) |
| **Revoked** | [Restore](https://userguide.qualytics.io/settings/access-tokens/personal-token/managing/restore-token/), [Delete](https://userguide.qualytics.io/settings/access-tokens/personal-token/managing/delete-token/) |
| **Expired** | [Delete](https://userguide.qualytics.io/settings/access-tokens/personal-token/managing/delete-token/) |

> **Note**
>
> The UI shows only **Delete** for expired tokens. An expired token no longer works, so you can delete it right away without revoking it first.

## 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](https://userguide.qualytics.io/settings/access-tokens/personal-token/managing/list-columns/) page.

> **Info: 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](https://userguide.qualytics.io/settings/access-tokens/personal-token/deep-dive/best-practices/) page.

*Last updated: November 13, 2026.*