API Tokens

/user/api-tokens

Create, list and revoke personal API tokens. Tokens are attached to your user account and act with your permissions. These endpoints require a login session token (JWT) — an API token cannot be used to manage API tokens.

GET/user/api-tokensList your API tokens POST/user/api-tokensCreate an API token DELETE/user/api-tokens/:tokenIdRevoke an API token

GET/user/api-tokens

List your API tokens

Auth required

Returns your active (non-revoked) API tokens, newest first. Token values are never returned — only the first characters (tokenPrefix) so you can tell tokens apart. Expired tokens remain listed until revoked.

Errors

401No token provided
403Invalid session token, or the request was authenticated with an API token

Request

curl -X GET "https://app.ummahspot.com/user/api-tokens" \
  -H "Authorization: Bearer $SHARH_TOKEN"

Response · 200

{
  "tokens": [
    {
      "id": "66f1c2a4e8b9a1d2c3f4a5b6",
      "name": "Flashcard sync script",
      "tokenPrefix": "sharh_pat_Xk3f9Q",
      "createdAt": "2026-09-18T14:02:11.000Z",
      "lastUsedAt": "2026-09-18T16:40:52.000Z",
      "expiresAt": "2026-12-17T14:02:11.000Z"
    }
  ]
}

POST/user/api-tokens

Create an API token

Auth required

Mints a new API token attached to your account. The plaintext token is returned once in this response and cannot be retrieved again — only a SHA-256 hash is stored. Each account can hold up to 10 active tokens.

Body parameters

`name`required string	Label for the token, up to 100 characters
`expiresInDays` number	Whole number of days until the token expires (1–365). Omit or send null for a token that never expires.Default: `null`

Errors

400Missing or too-long name, invalid expiresInDays, or the 10 active token limit was reached
401No token provided
403Invalid session token, or the request was authenticated with an API token

Request

curl -X POST "https://app.ummahspot.com/user/api-tokens" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'

Response · 201

{
  "token": "sharh_pat_Xk3f9Q...",
  "apiToken": {
    "id": "66f1c2a4e8b9a1d2c3f4a5b6",
    "name": "Flashcard sync script",
    "tokenPrefix": "sharh_pat_Xk3f9Q",
    "createdAt": "2026-09-18T14:02:11.000Z",
    "lastUsedAt": null,
    "expiresAt": "2026-12-17T14:02:11.000Z"
  }
}

DELETE/user/api-tokens/:tokenId

Revoke an API token

Auth required

Revokes one of your API tokens. It stops working immediately and cannot be restored.

Path parameters

tokenId

string

The token id from the list endpoint

Errors

401No token provided
403Invalid session token, or the request was authenticated with an API token
404Token not found, already revoked, or belongs to another user

Request

curl -X DELETE "https://app.ummahspot.com/user/api-tokens/:tokenId" \
  -H "Authorization: Bearer $SHARH_TOKEN"

Response · 200

{
  "message": "API token revoked"
}