New partner? OAuth requires a registered partner row. Apply for partner access first, then come back here to wire your client.
What is OAuth at Flexslot?
OAuth 2.0 is how third-party apps act on behalf of a Flexslot user without ever seeing that user’s password. Your app sends the user toflexslot.gg, the user clicks “Allow”, and you get back an access token scoped to exactly what you asked for.
If you’re building a deck tracker, a tournament platform, a Discord bot, a metagame analyzer, or any tool that needs to read or write a user’s decks, sideboard guides, or strategy content, OAuth is what you want.
Claude Code Skill
Let Claude Code build your integration for you
Quickstart
Get your first integration working in 10 minutes
Code samples
Drop-in Node.js, Python, and curl examples
Authorization Code Flow
The full end-to-end flow with PKCE
Scopes
Every scope and what it grants
Which auth method should I use?
Flexslot supports three ways for an external system to authenticate. Pick the one that matches your situation, not the one that’s easiest to ship.| Method | Acts as | Use when | Don’t use when |
|---|---|---|---|
| OAuth 2.0 | A specific Flexslot user (with their consent) | Your product is used by multiple Flexslot users and each one connects their own account | You need server-to-server access that isn’t tied to a user |
| Personal Access Token (PAT) | A single user (yourself) | You’re scripting against your own account or running a one-off integration | You’re building a product other Flexslot users will sign into |
| HMAC Webhook Signing | Flexslot itself (verifying us) | Receiving webhook callbacks from Flexslot | Calling our API |
If you’re not sure: use OAuth. PATs are only appropriate for personal scripts; HMAC is only for verifying inbound webhooks. Everything else is OAuth.
Terminology
A few terms you’ll see throughout these docs. We use the standard OAuth 2.0 vocabulary from RFC 6749.Resource Owner
Resource Owner
The Flexslot user whose decks, guides, or content your app wants to access. They’re the one clicking “Allow” on the consent screen.
Client
Client
Your application. Registered with Flexslot via the partner admin and identified by a
client_id.Authorization Server
Authorization Server
Resource Server
Resource Server
Flexslot’s REST API at
https://api.flexslot.gg/api/public/v1/.... Accepts the access tokens issued by the authorization server.Access Token
Access Token
A short-lived (1 hour) opaque string that proves your app is acting on behalf of a user. Sent as
Authorization: Bearer <token>.Refresh Token
Refresh Token
A longer-lived token used to get a new access token when the current one expires. Rotates on every use — store the new one.
Scope
Scope
A space-separated list of permissions your app requests, e.g.
decks:read sideboards:write. The user sees these on the consent screen.PKCE
PKCE
Proof Key for Code Exchange. A required security mechanism that binds the authorization code to your app, even if the code is intercepted. Mandatory for all clients.
Endpoints
The API endpoints (token, introspection, revocation) live underhttps://api.flexslot.gg. The authorization endpoint — the only one a browser navigates to — is the user-facing consent screen at https://flexslot.gg/oauth/authorize. We publish a discovery document (RFC 8414) listing the exact URLs; fetch it programmatically rather than hard-coding hosts.
| Endpoint | URL | Purpose |
|---|---|---|
| Discovery | https://api.flexslot.gg/.well-known/oauth-authorization-server | Lists all endpoints and supported capabilities |
| Authorization | https://flexslot.gg/oauth/authorize | Where you send the user’s browser to consent |
| Token | https://api.flexslot.gg/api/public/v1/oauth/token | Exchange code for tokens, or refresh tokens |
| Introspection | https://api.flexslot.gg/api/public/v1/oauth/introspect | Check whether a token is still valid (RFC 7662) |
| Revocation | https://api.flexslot.gg/api/public/v1/oauth/revoke | Revoke a token on logout (RFC 7009) |
The authorization endpoint is on
flexslot.gg, not api.flexslot.gg — it’s a web page the user’s browser opens, not an API call. The iss value returned on the callback is still the API issuer https://api.flexslot.gg; validate against that.What’s supported
| Capability | Supported | Notes |
|---|---|---|
| Authorization Code Grant | Yes | The only user-facing grant we support |
| PKCE (S256) | Required | All clients, public and confidential |
| Refresh Token Rotation | Yes | New refresh token on every refresh |
| Token Introspection | Yes | RFC 7662 |
| Token Revocation | Yes | RFC 7009 |
| Sender-Constrained Tokens (DPoP) | Yes (opt-in) | See DPoP |
| Client Credentials Grant | No | Use a PAT instead |
| Implicit Grant | No | Deprecated by RFC 9700 |
| Resource Owner Password Grant | No | Forbidden by RFC 9700 |
| Device Authorization Grant | No | Not currently supported |
Token lifetimes
| Token | Lifetime | Rotates? |
|---|---|---|
| Authorization code | 10 minutes | Single use |
| Access token | 1 hour | No (request a new one via refresh) |
| Refresh token | 30 days | Yes — every use |
Where to go next
Quickstart
Register a client and run the flow with curl
Security best practices
PKCE, state, redirect URIs, refresh rotation
Error reference
Every error code and how to fix it
Migrating from PAT
Already using a PAT? Add OAuth alongside.
