Authorization Flow
The Spellweave API uses OAuth 2.0 Authorization Code with PKCE. This is the most secure flow for apps that can protect a client secret.
Flow Diagram
1. Your App → User's Browser → GET /api/v1/oauth/authorize
2. User logs in and consents at spellweave.app
3. Spellweave → User's Browser → Your redirect_uri?code=...
4. Your Server → POST /api/v1/oauth/token (code + verifier)
5. Spellweave → Your Server → access_token + refresh_token
6. Your Server → GET /api/v1/decks (Bearer token)
Key Points
- PKCE is required. S256 only. No plain method.
- Redirect URIs must match exactly. No wildcards, no partial matches.
- HTTPS required. Except localhost for development.
- Access tokens expire in 1 hour. Use the refresh token to get a new pair.
- Refresh tokens are single-use. A new one is issued with every exchange.
Discovery Endpoint
OAuth server metadata is available at:
GET https://public-api.spellweave.app/.well-known/oauth-authorization-server