API keys and OAuth 2.0

Two paths: long-lived API keys for server-to-server work, and OAuth 2.0 with PKCE for user-delegated access.

1. Get an API key

Go to Admin → API Keys and click Create key. Choose the scopes the key should have. The key is shown once — copy it into your secrets store.

2. Authenticate requests

Send the key in the Authorization header.

curl https://teamstores.ai/api/public/v1/teams \
  -H "Authorization: Bearer $RYTE_API_KEY"

import { RyteClient } from "@ryte/sdk";

const ryte = new RyteClient({ apiKey: process.env.RYTE_API_KEY });
const { data: teams } = await ryte.teams.list({ limit: 10 });

3. Scopes

Every endpoint requires one of the scopes below. Granting * bypasses the check entirely — only use that for trusted internal tools.

4. OAuth 2.0 with PKCE

For apps that act on behalf of a user (parents, coaches), use the authorization-code flow with PKCE. Register your app under Admin → OAuth Apps first.

┌──────────┐  1. /oauth/authorize?client_id=…&code_challenge=…  ┌──────────┐
│  Client  │ ─────────────────────────────────────────────────▶ │   TeamStores.AI   │
│   App    │                                                    │   Auth   │
│          │ ◀───────────────  2. user logs in, consents ──────│          │
│          │  3. redirect_uri?code=…                            │          │
│          │ ◀──────────────────────────────────────────────────│          │
│          │  4. POST /oauth/token { code, code_verifier, … }   │          │
│          │ ─────────────────────────────────────────────────▶ │          │
│          │  5. { access_token, refresh_token, … }             │          │
│          │ ◀──────────────────────────────────────────────────│          │
└──────────┘                                                    └──────────┘

PKCE: generate the verifier and challenge

PKCE binds the authorization code to the requesting client. Native + SPA apps must use it; server-side apps may.

import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(32).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");

// Send the user to /oauth/authorize?code_challenge=${challenge}&…
// On callback, POST verifier alongside the code to /oauth/token.

5. Security best practices

• Never embed an API key in client-side code. Always proxy from your server.
• Rotate keys quarterly. Compromised keys can be revoked instantly in admin.
• Scope keys narrowly — never grant * to a key handed to a vendor.
• Use short-lived OAuth access tokens; rely on refresh tokens for long sessions.