Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flexslot.gg/llms.txt

Use this file to discover all available pages before exploring further.

If you’re already using a Personal Access Token (PAT) to call the Flexslot API, this page shows you how to add OAuth so multiple users can connect their own accounts. You don’t have to remove PAT support — the two coexist cleanly.

​
When to migrate

PATs and OAuth solve different problems. Migrate when at least one of these is true:

Multiple users

Your app is used by more than one Flexslot account. PATs are one-per-user; OAuth lets each user connect their own account.

You don't want to handle credentials

With OAuth, users never share their Flexslot password or token with you. They consent on flexslot.gg.

You need scope-limited access

PATs grant full account access. OAuth tokens are scoped to exactly what you requested.

You need revocation hygiene

OAuth tokens auto-expire (1h access, 30d refresh) and can be revoked per-grant from /account/connected-apps.
If you’re scripting against your own account and nothing else, stay on PAT. It’s simpler and that’s what it’s for.

​
Side-by-side

The API call is identical. The difference is how you get the token. 
const PAT = process.env.FLEXSLOT_PAT  // user pasted this into your config

const res = await fetch('https://api.flexslot.gg/api/public/v1/decks/', {
  headers: { 'Authorization': `Bearer ${PAT}` },
})
The Authorization header is the same. Everything underneath — token lifetime, refresh, scope checks — changes.

​
Migration plan

1

Register an OAuth client

Partner admin → New Application. See Quickstart Step 1.
2

Add a 'Connect Flexslot' button

Sends the user through the OAuth flow (authorization code with PKCE).
3

Store tokens per-user

Add flexslot_access_token, flexslot_refresh_token, flexslot_expires_at to your user record. Encrypt at rest.
4

Pick the token at call time

If the user connected via OAuth, use their access token (refreshing if needed). Otherwise fall back to the PAT.
5

Migrate users gradually

Encourage existing users to reconnect via OAuth. You can keep PAT support indefinitely; this is purely a UX upgrade.

​
Token selection pattern

A common pattern: a single function that returns “the best available credential” for a given user. 
async function getFlexslotToken(userId) {
  const user = await db.users.findById(userId)

  // Preferred: OAuth
  if (user.flexslot_refresh_token) {
    if (Date.now() < user.flexslot_expires_at - 5 * 60 * 1000) {
      return user.flexslot_access_token
    }
    return await refreshFlexslotToken(user)
  }

  // Fallback: PAT
  if (user.flexslot_pat) {
    return user.flexslot_pat
  }

  throw new NotConnectedError(`User ${userId} hasn't connected Flexslot`)
}

​
What changes for your users

ConcernPATOAuth
How they grant accessPaste a token from settings into your appClick “Connect Flexslot”, consent on flexslot.gg
Scope of accessFull accountExactly the scopes you requested
LifetimeUntil manually revokedAccess: 1h, Refresh: 30d, auto-rotated
RevocationManual via Flexslot settingsOne click in /account/connected-apps
VisibilityToken in their hands and yoursToken only on your server; user sees a “Connected to YourApp” entry
Multi-user supportOne PAT per user, each pasted manuallyPer-user via consent flow
User trustToken is a credentialStandard “Sign in with Flexslot” UX

​
What stays the same

  • Endpoints: identical. GET /api/public/v1/decks/, etc.
  • Response shapes: identical.
  • Pagination, filtering: identical.
  • Webhook signing: not affected — that’s HMAC, separate from auth.
  • Rate limits: same per-account limits whether you use PAT or OAuth.

​
Adding the “Connect” UI

Most apps add a section to their existing settings page:
Flexslot Integration ☑ Connected as @username
[Disconnect] or ☐ Not connected
[Connect Flexslot]
The Connect button sends the user through the OAuth flow. The Disconnect button:
  1. Calls POST /api/public/v1/oauth/revoke with the user’s refresh token
  2. Clears flexslot_access_token, flexslot_refresh_token, flexslot_expires_at from your DB
curl -X POST https://api.flexslot.gg/api/public/v1/oauth/revoke \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "token=$REFRESH_TOKEN" \
  -d "token_type_hint=refresh_token"
See Connected Apps UX for the full UX pattern, including what to do when a user revokes from the Flexslot side.

​
Common pitfalls when migrating

PitfallWhyFix
Storing PAT and OAuth in the same columnType confusion at call timeSeparate columns: flexslot_pat, flexslot_access_token, flexslot_refresh_token
Forgetting to handle invalid_grant on refreshUser looks logged in but the next call failsCatch on refresh, mark user as disconnected, prompt re-auth
Asking for too many scopes up frontUser declines, conversion dropsStart with minimum scopes, request more via incremental authorization
Skipping state because “you have PKCE”They defend different attacksUse both. Always.
Logging the access_token in your migration runnerTokens persist in log aggregatorMask before logging

​
Should you remove PAT support?

You don’t have to. Some users prefer PATs:
  • Scripts that don’t have a browser
  • CI integrations
  • Personal automation
A clean approach: keep PAT support for personal use, OAuth for user-facing apps. The two patterns serve different audiences. If you do want to deprecate, give users a deprecation timeline and an obvious upgrade path. Don’t break their integrations silently.

​
Next steps

Quickstart

Get the first end-to-end flow working

Connected Apps UX

The UI patterns users expect

Scopes

Pick the right minimum-viable set

Errors

Handle revocation and refresh failures