Security Best Practices

Best practices for securing your API tokens and managing authentication safely.

Prefer JWT for Programmatic Access

Use POST /api/auth/token to get short-lived JWT access tokens (1 hour) instead of long-lived persistent tokens. JWTs expire automatically, reducing risk if leaked. Use refresh tokens (7 days) to get new access tokens without re-authenticating.

Token Storage

Store API tokens and refresh tokens securely. Never commit them to version control or expose them in client-side code. Use environment variables or secure secret management systems.

Use Minimal Scopes

Only request the scopes your application needs. If you only need to read data, request only read scopes when logging in: {"scopes": ["team-data:read"]}.

Refresh Token Rotation

Refresh tokens are rotated on every use — when you call /api/auth/token/refresh, the old refresh token is revoked and a new one is returned. This limits the window of exposure if a refresh token is compromised.

Revoke Unused Tokens

Regularly review your persistent vm_ tokens in account settings and revoke any that are no longer in use.

Rate Limits

The API enforces rate limits to ensure fair usage. Authentication endpoints use stricter limits to prevent brute force attacks. If you receive a 429 response, wait before retrying. The Retry-After header indicates when you can retry.