> For the complete documentation index, see [llms.txt](https://docs.stepsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stepsecurity.io/administration/short-lived-tokens.md).

# Short-lived tokens

Short-lived tokens are personal, time-bound bearer tokens for calling the StepSecurity API directly. Use them with the [StepSecurity MCP server](https://github.com/step-security/stepsecurity-mcp), custom scripts, CLIs, and any other tool that needs to authenticate to the StepSecurity API on your behalf.

Tokens are scoped to the permissions you select and expire automatically. The maximum lifetime is 12 hours, and tokens cannot be extended once created.

<figure><img src="/files/32pDKK9xCIPPxWyKtv7o" alt=""><figcaption></figcaption></figure>

### When to use a short-lived token

Short-lived tokens are designed for any scenario where you need to authenticate as yourself to the StepSecurity API outside of the web app:

* StepSecurity MCP server, when connecting an AI assistant to your StepSecurity workspace
* Local scripts and CLIs that query the StepSecurity API
* One-off automations, ad-hoc data exports, or debugging API calls from your machine

For long-lived, service-to-service automation, use an [Organization](/workspace/settings/stepsecurity-api-org-access.md) or [Tenant](/administration/admin-console/integrations/stepsecurity-api-tenant-access.md) API key instead. Short-lived tokens are tied to your user account and your effective permissions.

### Where to find your tokens

You can open the personal access tokens page in two ways:

* Click your avatar in the top right and select Short-lived tokens

<figure><img src="/files/6839vzwZ7eXtr7YEbFMQ" alt=""><figcaption></figcaption></figure>

* Go directly to [https://app.stepsecurity.io/me/tokens](https://app.stepsecurity.io/me/tokenshttps://app.stepsecurity.io/me/tokens)

Each tenant has its own independent token list. If you belong to multiple tenants, use the Tenant selector at the top of the page to switch between them. A token issued for one tenant cannot be used to access another.

<figure><img src="/files/n1GMsPh4V09GVGWOZf0H" alt=""><figcaption></figcaption></figure>

### Creating a token

* On the personal access tokens page, click Create token

<figure><img src="/files/qwihZpTRvBk6H0CcQtaf" alt=""><figcaption></figcaption></figure>

* (Optional) Give the token a Name. The name is shown in your token list and cannot be changed later
* Choose a Duration: 1 hour, 4 hours, 8 hours, or Max (12 hours). Pick the shortest duration that fits your task
* Select Permissions. Use Read all or Read & write all as shortcuts, or expand each category to pick specific permissions
* Click Create token

<figure><img src="/files/k2QiybY7amluwV7YblgW" alt=""><figcaption></figcaption></figure>

* Copy the raw token from the confirmation screen and store it somewhere safe

The raw token is shown only once, immediately after creation. If you close the screen without copying it, you will need to create a new token.

<figure><img src="/files/v8JZnaVgtjy6SQAfiJ3e" alt=""><figcaption></figcaption></figure>

### Revoking a token

To revoke a token before it expires, go to <https://app.stepsecurity.io/me/tokens>, find the token in the list, and remove it. Revocation takes effect immediately. Any script, CLI, or MCP client still using the token will start receiving authentication errors on the next request.

<figure><img src="/files/amDMQDwjH0XDfAPQDksT" alt=""><figcaption></figcaption></figure>

You cannot extend a token. If you need more time, revoke the existing one and mint a new token with the duration and permissions you need.

### Security best practices

* Pick the shortest duration that fits your task. The default of 1 hour is appropriate for most interactive use
* Grant only the permissions the script, CLI, or MCP client actually needs. Avoid Read & write all unless required
* Store the raw token in a secure credential store (system keychain, secret manager). Do not commit it to source control
* Rotate tokens by revoking and re-creating them. Treat any token that may have been exposed as compromised
* Use Organization or Tenant API keys for service-to-service automation that needs to outlive 12 hours


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stepsecurity.io/administration/short-lived-tokens.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.