Tokens
The Spellweave API issues two types of tokens: access tokens for API calls and refresh tokens for obtaining new access tokens.
| Token | Lifetime | Notes |
|---|---|---|
| Access Token | 1 hour | Used in Authorization header for API calls |
| Refresh Token | 90 days | Single-use. Exchanged for a new token pair. |
| Authorization Code | 10 minutes | Single-use. Exchanged for tokens via POST /token. |
Token Rotation
Every time you use a refresh token, it is invalidated and a new refresh token is returned alongside the new access token. This is called token rotation. Store the new refresh token immediately.
If a refresh token is used more than once (indicating it may have been stolen), all tokens in the same family are automatically revoked for security. Both the legitimate user and the attacker lose access, and the user must re-authorize.
Token Storage
- Server-side apps: Store tokens in your database, encrypted at rest.
- Never store tokens in: localStorage, sessionStorage, cookies accessible to JavaScript, URL parameters, or client-side code.
- Token exchange must happen server-side. Your client secret should never be exposed in browser code.
Revocation
Users can revoke your app's access at any time from their Spellweave account settings. When access is revoked, all active tokens for your app are immediately invalidated.
Your app should also revoke tokens when a user logs out or disconnects their Spellweave account. Use the POST /api/v1/oauth/revoke endpoint.