> Create, use, and revoke API tokens for server-to-server integrations

# API Tokens

API tokens are long-lived credentials for server integrations, scripts, and automated workflows.
They stay valid until you revoke them.

## Creating tokens

In the admin panel:

1. Go to **Settings > API Tokens**
2. Click **Create Token**
3. Enter a name that identifies the token's purpose
4. Select permissions (see below)
5. Click **Create**

> **Copy your token**
> The token is only shown once. Store it securely.

Via the API:

```graphql filename="mutation"
mutation {
  createPyloApiKey(
    input: {
      name: "CI/CD Integration"
      permissions: ["read", "write"]
    }
  ) {
    data {
      id
      name
      token
    }
  }
}
```

## Using tokens

Send the token in the `pylo-api-key` header:

```bash filename="terminal"
curl -X POST https://api.pyloapp.com/graphql \
  -H "Content-Type: application/json" \
  -H "pylo-api-key: YOUR_API_TOKEN" \
  -d '{"query": "{ customerList { data { id name } } }"}'
```

In the SDKs, store the token in the `PYLO_API_KEY` environment variable and pass it as
`apiKey: process.env.PYLO_API_KEY!` in `pylo.config.ts` (codegen) and `createPyloNode` /
`createPyloServer` (data access). See the [quickstarts](/getting-started/quickstart-nextjs).

## Permissions

| Permission | Description                                        |
| ---------- | -------------------------------------------------- |
| `read`     | Query entities (list and by-ID)                    |
| `write`    | Create, update, and delete entities                |
| `admin`    | Full access including user management and settings |

Permissions combine: a token with `["read", "write"]` can query and mutate data but cannot manage
users or app settings.

> **Least privilege**
> Create tokens with the minimum permissions required. Give a read-only integration `read` and
> nothing else.

## Revoking tokens

In the admin panel: **Settings > API Tokens**, find the token, click **Delete**. Via the API:

```graphql filename="mutation"
mutation {
  deletePyloApiKey(ids: ["token-id"]) {
    data {
      success
    }
  }
}
```

Revoked tokens stop working immediately, and requests carrying one get an `UNAUTHORIZED` error.