Personal Access Tokens API

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.

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

Token object (metadata)

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

string

required

UUID identifying the token. Use this to delete the token.

string

required

Human-readable name for this token, e.g. "Claude Desktop".

string

required

ISO 8601 date string of when the token was created.

string

ISO 8601 date string of the most recent authenticated request using this token. null if the token has never been used.

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

string

required

A descriptive name for this token. Use something that identifies the integration, e.g. "Claude Desktop", "Cursor", or "nightly-export-script".

Response

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

string

required

UUID of the newly created token.

string

required

The label you provided.

string

required

ISO 8601 date string.

string

required

null for a newly created token.

string

required

The raw token value. Starts with spote_ followed by 32 hex characters. This field is only present in the creation response.

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.

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"}'

{
  "_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.

curl https://your-spote-app.com/api/settings/token \
  -H "Authorization: Bearer spote_YOUR_TOKEN"

[
  {
    "_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

string

required

The UUID of the token to delete. Retrieve this from GET /api/settings/token.

Response

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

curl -X DELETE https://your-spote-app.com/api/settings/token/t1a2b3c4-... \
  -H "Authorization: Bearer spote_YOUR_TOKEN"

Overview

Endpoints

Personal Access Tokens API

Token object (metadata)

POST /api/settings/token

Request body

Response

GET /api/settings/token

Response

DELETE /api/settings/token/:id

Path parameters

Response

​Token object (metadata)

​POST /api/settings/token

​Request body

​Response

​GET /api/settings/token

​Response

​DELETE /api/settings/token/:id

​Path parameters

​Response

Token object (metadata)

POST /api/settings/token

Request body

Response

GET /api/settings/token

Response

DELETE /api/settings/token/:id

Path parameters

Response