<a id="managing-your-api-tokens"></a>
<a id="api-tokens"></a>
# Managing your API tokens

This page covers the **user-facing** flow for creating and revoking API tokens from your Profile. For the protocol details (header format, `api-token-auth/` endpoint, behaviour for SSO users), see [Token Authentication](authentication.html.md#api-token-authentication).

Access to the API Tokens tab comes from your [Organization Role](../organizations/roles.html.md#organization-roles), through the **Can create and manage personal API tokens** permission. Someone who can administer permissions chooses your role on the [Organization Team](../organizations/team.html.md#organization-team) page.

<a id="creating-a-token"></a>
## Creating a token

1. Visit your Profile page and select the **API Tokens** tab.
2. Click **Create new token**.
3. Give the token a memorable name — for example `ci-pipeline`, `my-laptop`, or `data-export-script`. Names must be unique across your own tokens.
4. Click **Create token**. The full token value is shown **once** in the dialog.

**Copy the token value before closing the dialog.** Tokens are stored as one-way hashes; the full value cannot be recovered once you dismiss the dialog. If you lose the value, revoke the token and create a new one.

You will receive an email confirming that a token was created on your account. The email includes the time, IP address, and user agent of the request — if you didn't just create a token, revoke it from the API Tokens tab and contact your Organization administrator.

<a id="reviewing-and-revoking"></a>
## Reviewing and revoking

The API Tokens tab lists each of your active tokens with:

- The name you gave it
- A short prefix of the token value (for matching to a token you're holding elsewhere)
- When it was created
- When it was last used, including the request method, path, and IP address

Click **Revoke** on a row and confirm in the dialog that appears. Once revoked, any application still using the token will start receiving `401 Unauthorized` responses immediately. A confirmation email is sent to your account whenever a token is revoked.

<a id="tips"></a>
## Tips

- **Rotate tokens periodically.** Create a new token, deploy it to your integration, then revoke the old one once you're confident the new one is in use everywhere.
- **One token per integration.** Naming each token after where it's used (e.g. `laptop-claude`, `ci-build`) makes the "last used" column meaningful and lets you revoke just the affected token if a single integration is compromised.
- **Revoke tokens for departing team members.** When a colleague leaves, someone who can administer permissions should disable their account and revoke their tokens. Disabling the **Can create and manage personal API tokens** permission also blocks the user's existing tokens from authenticating, but the rows remain in the database — if the permission is re-enabled later, those tokens become usable again. Revoke the tokens explicitly to permanently destroy them.
