OAuth Quickstart - Flexslot V2

Ten minutes from now you’ll have an access token in your terminal and you’ll have called the Flexslot API with it. We’ll use curl plus a tiny shell snippet so you can see exactly what’s happening on the wire.

Prerequisites

A Flexslot account (sign up if you don’t have one)
openssl, curl, and a Unix shell
A redirect URI you control. For this guide we’ll use http://localhost:8765/callback and run a one-line Python listener.

Step 1 — Register your client

Open the partner admin

Sign in at flexslot.gg and open Account → API access (the canonical link is flexslot.gg/account?section=api-access; the /settings URL redirects to /account). In the OAuth applications card, click New application.

Fill in the application

Name: Quickstart Test (whatever you like)
Application type: Public (no client secret) for a CLI/native app, or Confidential for a server app
Redirect URIs: http://localhost:8765/callback
Allowed scopes: check decks:read for now

Save the client_id

You’ll see a client_id like flx_client_01HX2K…. If you chose Confidential, you also get a client_secret shown once — copy it now.

Confidential client secrets are shown exactly once at creation time. If you lose it, rotate the secret from the admin — there’s no way to retrieve the original value.

Step 2 — Generate PKCE values

PKCE binds the authorization code to your client. Every authorization request needs a freshly generated code_verifier and code_challenge.

# Generate a random 32-byte code_verifier (43 chars base64url, no padding)
VERIFIER=$(openssl rand 32 | base64 | tr '+/' '-_' | tr -d '=\n')

# Derive the SHA-256 challenge
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary \
  | base64 | tr '+/' '-_' | tr -d '=\n')

echo "verifier=$VERIFIER"
echo "challenge=$CHALLENGE"

import crypto from 'node:crypto'

const b64url = (buf) =>
  buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')

const verifier = b64url(crypto.randomBytes(32))
const challenge = b64url(crypto.createHash('sha256').update(verifier).digest())

console.log({ verifier, challenge })

import base64, hashlib, secrets

verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b'=').decode()
challenge = base64.urlsafe_b64encode(
    hashlib.sha256(verifier.encode()).digest()
).rstrip(b'=').decode()

print(f"verifier={verifier}")
print(f"challenge={challenge}")

Keep the verifier somewhere your callback handler can read it. We’ll need it in step 4. The challenge goes on the wire; the verifier stays secret in your app.

Step 3 — Send the user to /authorize

Open this URL in your browser. Replace CLIENT_ID and use the CHALLENGE you just generated.

STATE=$(openssl rand -hex 16)

open "https://flexslot.gg/oauth/authorize?\
response_type=code&\
client_id=CLIENT_ID&\
redirect_uri=http://localhost:8765/callback&\
scope=decks:read&\
state=$STATE&\
code_challenge=$CHALLENGE&\
code_challenge_method=S256"

You’ll see the Flexslot consent screen. Click Allow and your browser will be redirected to http://localhost:8765/callback?code=...&state=...&iss=https://api.flexslot.gg.

Step 4 — Capture the code with a one-line listener

Run this in a second terminal before you click Allow:

python3 -c "
from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.parse import urlparse, parse_qs
class H(BaseHTTPRequestHandler):
    def do_GET(s):
        q = parse_qs(urlparse(s.path).query)
        print('CODE=', q.get('code', [''])[0])
        print('STATE=', q.get('state', [''])[0])
        print('ISS=', q.get('iss', [''])[0])
        s.send_response(200); s.end_headers()
        s.wfile.write(b'You can close this tab.')
HTTPServer(('localhost', 8765), H).serve_forever()
"

After approving, your terminal prints the code. Validate that state matches the value you sent, and that iss equals https://api.flexslot.gg. If either check fails, stop — that’s an attack signal, not an error.

Step 5 — Exchange the code for tokens

CODE=<paste-the-code-from-step-4>

# For a Confidential client (with secret):
curl -sS -X POST https://api.flexslot.gg/api/public/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=$CODE" \
  -d "redirect_uri=http://localhost:8765/callback" \
  -d "code_verifier=$VERIFIER"

# For a Public client (no secret):
curl -sS -X POST https://api.flexslot.gg/api/public/v1/oauth/token \
  -d "grant_type=authorization_code" \
  -d "client_id=$CLIENT_ID" \
  -d "code=$CODE" \
  -d "redirect_uri=http://localhost:8765/callback" \
  -d "code_verifier=$VERIFIER"

You’ll get back something like:

{
  "access_token": "flx_at_01HX2K6F8N9PRSTUVWXYZA…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "flx_rt_01HX2K6F8N9PRSTUVWXYZB…",
  "scope": "decks:read"
}

Step 6 — Call the API

ACCESS_TOKEN=<paste-the-access_token>

curl -sS https://api.flexslot.gg/api/public/v1/games/magic-the-gathering/decks \
  -H "Authorization: Bearer $ACCESS_TOKEN"

You should see a paginated list of the user’s decks. Congratulations, you have a working OAuth integration.

Step 7 — Identify the connected user

To render “Connected as: …” in your UI, call the user probe with the same access token. It returns the bare Firebase id and the user’s Flexslot handle:

curl -sS https://api.flexslot.gg/api/public/v1/_probe/user \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "caller": "partner:your-slug+user:gZUcFcNiXQNFH3unke6X8gVox5Y2",
  "user": {
    "id": "gZUcFcNiXQNFH3unke6X8gVox5Y2",
    "username": "george-cardeio"
  },
  "scopes": ["decks:read"],
  "tier": "standard"
}

user.id is the bare Firebase id and is identical to author.id on that user’s public decks — use it to correlate the connected account with the deck data you fetch. user.username is the same handle shown on the consent screen. No extra scope (no profile/email) is required: identity here is exactly what the user already saw and approved at consent. The user’s email is intentionally not returned — it isn’t consistently shown at consent, so it would be undisclosed PII for a partner that only requested resource scopes. caller is an opaque composite principal — stable for rate-limiting and audit, but not meant for display.

What you just did

Registered a client

The partner admin gave you a client_id (and optionally a client_secret) that identifies your app.

Generated PKCE

The code_verifier proves your app is the same app that initiated the flow, even if someone intercepts the code.

Got user consent

The user saw exactly which scopes you requested and clicked Allow.

Validated the response

You checked state (CSRF defense) and iss (mix-up defense, RFC 9207).

Exchanged code for tokens

The token endpoint verified the code_verifier and returned access + refresh tokens.

Called the API

A Bearer token in the Authorization header is all the API needs.

Next steps

Code samples

Production-ready Express and Flask implementations

Authorization Code Flow

The full flow with a sequence diagram

Refresh tokens

How to keep the user logged in

Scopes

Request additional permissions

This quickstart used a public client (no secret) to keep things simple. For a server-side app, choose Confidential in step 1 and send the client_secret via HTTP Basic auth as shown in step 5.

​Prerequisites

​Step 1 — Register your client

​Step 2 — Generate PKCE values

​Step 3 — Send the user to /authorize

​Step 4 — Capture the code with a one-line listener

​Step 5 — Exchange the code for tokens

​Step 6 — Call the API

​Step 7 — Identify the connected user

​What you just did

​Next steps

Code samples

Authorization Code Flow

Refresh tokens

Scopes

Prerequisites

Step 1 — Register your client

Step 2 — Generate PKCE values

Step 3 — Send the user to /authorize

Step 4 — Capture the code with a one-line listener

Step 5 — Exchange the code for tokens

Step 6 — Call the API

Step 7 — Identify the connected user

What you just did

Next steps