Skip to main content

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.

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.
​
_id
string
required
UUID identifying the token. Use this to delete the token.
​
label
string
required
Human-readable name for this token, e.g. "Claude Desktop".
​
created_at
string
required
ISO 8601 date string of when the token was created.
​
last_used_at
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

​
label
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.
​
_id
string
required
UUID of the newly created token.
​
label
string
required
The label you provided.
​
created_at
string
required
ISO 8601 date string.
​
last_used_at
string
required
null for a newly created token.
​
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

​
id
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"