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

# Personal Access Tokens API

> Create, list, and revoke Personal Access Tokens via the API. Tokens authenticate REST API and MCP requests. The raw token value is returned only at creation.

The tokens API lets you manage Personal Access Tokens (PATs) programmatically. PATs are the primary way to authenticate API and MCP requests from AI agents and scripts. The server stores only a hashed representation of each token — the raw value is returned exactly once at creation.

<Tip>
  Create one token per integration (Claude Desktop, Cursor, personal scripts) so you can revoke individual access without affecting other tools.
</Tip>

## Token object (metadata)

All list and delete operations work with the token metadata object, which never includes the raw token value.

<ResponseField name="_id" type="string" required>
  UUID identifying the token. Use this to delete the token.
</ResponseField>

<ResponseField name="label" type="string" required>
  Human-readable name for this token, e.g. `"Claude Desktop"`.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 date string of when the token was created.
</ResponseField>

<ResponseField name="last_used_at" type="string">
  ISO 8601 date string of the most recent authenticated request using this token. `null` if the token has never been used.
</ResponseField>

***

## POST /api/settings/token

Create a new Personal Access Token. The raw token value is returned in this response only — it is not stored in plaintext and cannot be retrieved again.

### Request body

<ParamField body="label" type="string" required>
  A descriptive name for this token. Use something that identifies the integration, e.g. `"Claude Desktop"`, `"Cursor"`, or `"nightly-export-script"`.
</ParamField>

### Response

**201 Created** — returns the token metadata plus the raw `token` field.

<ResponseField name="_id" type="string" required>
  UUID of the newly created token.
</ResponseField>

<ResponseField name="label" type="string" required>
  The label you provided.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 date string.
</ResponseField>

<ResponseField name="last_used_at" type="string" required>
  `null` for a newly created token.
</ResponseField>

<ResponseField name="token" type="string" required>
  The raw token value. Starts with `spote_` followed by 32 hex characters. This field is only present in the creation response.
</ResponseField>

<Warning>
  The `token` field is only returned once — at creation. Store it immediately in a secrets manager or environment variable. Subsequent requests to list tokens return metadata only, without the raw token value.
</Warning>

```bash theme={null}
curl -X POST https://your-spote-app.com/api/settings/token \
  -H "Authorization: Bearer spote_YOUR_EXISTING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "Claude Desktop"}'
```

```json theme={null}
{
  "_id": "t1a2b3c4-...",
  "label": "Claude Desktop",
  "created_at": "2024-01-15T10:30:00Z",
  "last_used_at": null,
  "token": "spote_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
```

***

## GET /api/settings/token

List all Personal Access Tokens for your account. Token values are not included — only metadata.

### Response

**200 OK** — array of token metadata objects, without the raw `token` field.

```bash theme={null}
curl https://your-spote-app.com/api/settings/token \
  -H "Authorization: Bearer spote_YOUR_TOKEN"
```

```json theme={null}
[
  {
    "_id": "t1a2b3c4-...",
    "label": "Claude Desktop",
    "created_at": "2024-01-15T10:30:00Z",
    "last_used_at": "2024-01-20T08:45:00Z"
  },
  {
    "_id": "t5d6e7f8-...",
    "label": "Cursor",
    "created_at": "2024-01-18T14:00:00Z",
    "last_used_at": null
  }
]
```

***

## DELETE /api/settings/token/:id

Delete a Personal Access Token. The token is invalidated immediately — any in-flight requests using this token will be rejected.

### Path parameters

<ParamField path="id" type="string" required>
  The UUID of the token to delete. Retrieve this from `GET /api/settings/token`.
</ParamField>

### Response

**204 No Content** — the token has been deleted and is no longer valid.

```bash theme={null}
curl -X DELETE https://your-spote-app.com/api/settings/token/t1a2b3c4-... \
  -H "Authorization: Bearer spote_YOUR_TOKEN"
```