Authentication

The Tholos API supports three authentication methods. For programmatic access and third-party integrations, Personal Access Tokens (PATs) are recommended.

Personal Access Tokens (PATs)

PATs are the primary way to authenticate with the Tholos API from scripts, CI/CD pipelines, and custom integrations. A PAT is tied to your user account and carries the same access and permissions.

Creating a token

1. Open the Tholos Dashboard
2. Go to Settings > Account > Advanced
3. Click Create Token
4. Enter a descriptive name (e.g., “CI/CD Pipeline” or “Trading Bot”)
5. Optionally set an expiration date
6. Copy the token — it is only displayed once

Using a token

Include the token in the Authorization header as a Bearer token:

curl https://api.tholos.app/user/me \
  -H "Authorization: Bearer tholos_pat_abc123..."

All PATs start with the tholos_pat_ prefix.

Managing tokens

Operation	Endpoint	Description
List tokens	GET /personal-access-token	List all active tokens (values are never included)
Get token details	GET /personal-access-token/{id}	View name, dates, enabled status
Update token	PATCH /personal-access-token/{id}	Change name, expiration, or enabled status
Rotate token	POST /personal-access-token/{id}/rotate	Generate a new token value, invalidate the old one
Revoke token	DELETE /personal-access-token/{id}	Soft-delete a token (cannot be undone)

Token rotation

When you rotate a token, a new value is generated and the old one is invalidated after a 5-minute grace period. This allows you to update your integrations without downtime.

curl -X POST https://api.tholos.app/personal-access-token/42/rotate \
  -H "Authorization: Bearer tholos_pat_old_token..."

The response includes the new token value — store it immediately.

Token expiration

If a token has an expiresAt date and that date has passed, the token is automatically disabled on the next authentication attempt. You can set or update expiration via the API:

curl -X PATCH https://api.tholos.app/personal-access-token/42 \
  -H "Authorization: Bearer $THOLOS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expiresAt": 1735689600}'

The expiresAt field is a Unix timestamp in seconds.

Caution

PATs are tied to your account and have the same access and privileges. Do not share a PAT with anyone. If a token is compromised, revoke it immediately.

Session cookies

Session cookies are used by the Tholos Dashboard and mobile app. They are set during the OAuth login flow and are not intended for programmatic use. If you see a next-auth.session-token cookie, that is the session-based auth mechanism.

You should not use session cookies for API integrations — use PATs instead.

Internal service keys

Internal service keys are used for service-to-service communication within the Tholos infrastructure. These are not available to external developers.

Rate limiting

All API endpoints are rate-limited. Limits vary by endpoint, but typical limits are:

Endpoint type	Rate limit
Read operations	20 requests / 60 seconds
Write operations	10 requests / 60 seconds
Token management	3–10 requests / 60 seconds
User profile	300 requests / 60 seconds

When you exceed a rate limit, the API returns a 429 Too Many Requests response. Back off and retry after the window resets.

Error responses

Authentication errors return standard HTTP status codes:

Status	Meaning
401 Unauthorized	Missing or invalid token
403 Forbidden	Token is valid but lacks permission for the requested resource
429 Too Many Requests	Rate limit exceeded