---
title: "API tokens"
description: "Create, use, extend and revoke long-lived MySpec API tokens for servers, containers and CI."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.myspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API tokens

An API token lets the MySpec MCP servers work without a browser sign-in. Use one
for anything that runs without a person present: a server, a container, a CI
job or a shared machine.

API tokens start with `msp_pat_`.

## Create a token

1. **Open API tokens**

   In [MySpec](https://app.myspec.dev), open the avatar menu and choose
   **API tokens**, then select **Create token**.
2. **Fill in the details**

   - **Name**: so you can tell tokens apart later, for example "CI" or "My laptop".
   - **Organization**: the token only works for this organization.
   - **Access**: **Read only** can read projects and files but cannot change
     anything. **Read and write** can also change them.
   - **Expires after**: 30, 90, 180 or 365 days.
3. **Copy the token**

   The token is shown **once**. Copy it into your secret store before you close
   the panel. If you lose it, revoke it and create a new one.

The organization and access of a token are fixed when you create it. To change
either, create a new token.

A token acts as you. It can never do more than your
[project role](/guides/teams-and-project-access/) allows on each project, and a
**Read only** token acts as **Read** on every project, even where you are
Admin.

## Use a token with the remote server

Send the token as a bearer token:

```http
Authorization: Bearer msp_pat_…
```

See [Remote MCP server](/mcp/remote-server/#connect-with-an-api-token) for
client configuration examples.

## Use a token with the local server

The simplest option is the `MYSPEC_API_TOKEN` environment variable in your MCP
client's configuration:

```json title=".mcp.json"
{
  "mcpServers": {
    "myspec": {
      "command": "npx",
      "args": ["-y", "@myspec/mcp-server"],
      "env": { "MYSPEC_API_TOKEN": "msp_pat_…" }
    }
  }
}
```

On a shared machine, environment variables can be seen by other processes. A
credentials file that only you can read is the tighter choice. Save it as
`~/.myspec/oauth_creds.json`:

```json title="~/.myspec/oauth_creds.json"
{ "apiToken": "msp_pat_…" }
```

```bash
chmod 600 ~/.myspec/oauth_creds.json
```

The server refuses a credentials file that other users can read.

### Which credential wins

The local server uses the first of these that is set, and only that one:

1. The `MYSPEC_API_TOKEN` environment variable.
2. `apiToken` in `~/.myspec/oauth_creds.json`.
3. The sign-in saved by `login`.

If the chosen token is rejected, the server stops with an error instead of
falling back to another identity.

### Check a token

```bash
MYSPEC_API_TOKEN=msp_pat_… npx -y @myspec/mcp-server auth status
```

It prints the organization and whether the token is read-only or read-write,
and exits with `0` when the token works.

## Extend a token

On the **API tokens** page, select **Refresh** next to the token and choose a new
expiry. The token value does not change, so anything already using it keeps
working without reconfiguration.

A token can be extended up to two years after it was created. After that,
create a new one.

## Revoke a token

Select **Revoke** next to the token. It stops working and cannot be re-enabled.

- The remote server can keep accepting it for up to about a minute.
- A local server that is already running can keep using its current sign-in for
  up to 15 minutes. Restart it to cut access off at once.

The page also shows when each token was last used, which helps you find tokens
you no longer need.

## Keep tokens safe

- Treat a token like a password. Never commit it to a repository, paste it into
  a chat or put it in a URL.
- Give each machine or pipeline its own token, so you can revoke one without
  breaking the others.
- Prefer **Read only** unless the agent needs to change things.
- Choose the shortest expiry that works for you, and revoke tokens you no longer use.

## Troubleshooting

| Status | Meaning |
|---|---|
| **Unusable** on the API tokens page | You no longer have access to the token's organization. Create a new token for an organization you belong to. |
| `401` from a server | The token is unknown, revoked or expired. Create a new one. |
| `403` from a server | The token's organization is gone, or you are no longer a member of it. |
| `429` from a server | Too many requests. Wait for the time in the `Retry-After` header, then try again. |
| A write fails with a read-only error | The token is **Read only**. Create a **Read and write** token. |
| A tool fails with "permission denied" | Your role on the project is too low. A new token will not help; see [Permission denied](/mcp/troubleshooting/#permission-denied-for-your-project-role). |

Source: https://docs.myspec.dev/mcp/api-tokens/index.mdx