Sign in with AcademyOS

How it fits together

With the partner API you act as yourself: an organisation-level key lists your licensed catalog and grants access to your customers. Sign in with AcademyOS is the opposite direction: an AcademyOS learner signs in on your site and consents to you reading their identity — and, with an extra scope, the marketplace courses they hold. You never see their password; they can revoke you at any time; every token you hold is scoped to exactly what they agreed to.

It is standard OAuth 2.0 authorization code + PKCE with OpenID Connect on top (discovery, RS256 id_tokens, JWKS, userinfo). Any off-the-shelf OIDC client library works: point it at the discovery document and you are most of the way done.

Registration

Register your partner organisation in the developer portal — a signed-in AcademyOS account with a confirmed email is all it takes — and create your client there. Clients work immediately; every use of one is gated by the learner's consent. Catalog licensing for the partner API key is a separate, commercial decision you request from the same page. You will need:

• Your redirect URIs — exact match, https required outside development (loopback IPs such as http://127.0.0.1:4567/callback are accepted for local testing).
• Whether your client is confidential (you can keep a secret server-side: a classic web app) or public (SPA or mobile app; no secret, PKCE carries the proof). The client type cannot be changed later — a different type is a new client.
• Optionally, a narrower scope set than the default four (see Scopes).
• The name to show on the consent screen, and a technical contact email.

You receive a client_id, and for confidential clients a client_secret that is shown exactly once, at creation — we store only its SHA-256 digest, exactly like partner API keys. Lost secrets are rotated, not recovered; rotation re-displays a new secret once and invalidates the old one immediately.

One partner can hold several clients (one per platform). Every client, token and consent of yours dies the moment your partner account is deactivated — the same kill switch as your API keys.

Register your app

Endpoints

CORS is deliberately open only on the cookie-less, public endpoints a browser-based PKCE client must call; everything else keeps the browser's same-origin default. /oauth/authorize is a redirect target, not an API — do not fetch it.

Scopes

Note the colon in enrollments:read. Unknown scopes are rejected with the standard invalid_scope error, and a per-client configuration can narrow this list further. Request the smallest set you need: the consent screen shows every scope to the learner, and asking for enrollments:read you don't use costs you consent-screen trust.

The authorization flow

Authorization code with PKCE (S256). PKCE is required — public clients cannot complete the flow without it, and confidential clients that send it get it verified. No implicit, no password, no client-credentials grant: a partner acting as itself uses its partner API key, not OAuth.

1. Redirect the learner (top-level) to:

   GET https://app.academyos.app/oauth/authorize?client_id=…&redirect_uri=…&response_type=code
       &scope=openid+email+enrollments:read
       &state=<random>&nonce=<random>
       &code_challenge=<S256(code_verifier)>&code_challenge_method=S256

2. The learner signs in to AcademyOS if they aren't already — including their 2FA step — and lands back on the consent screen automatically. The screen names your app and your partner organisation and lists the scopes. They approve or deny.

3. Approval redirects to your redirect_uri with ?code=…&state=…. The code is single-use and lives 10 minutes.

4. Exchange it (server-side, or from the SPA — the endpoint is CORS-open):

   POST https://app.academyos.app/oauth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&code=…&redirect_uri=…
   &client_id=…&code_verifier=…
   [&client_secret=… for confidential clients]

   {
     "access_token": "…", "token_type": "Bearer", "expires_in": 7200,
     "refresh_token": "…", "scope": "openid email enrollments:read",
     "created_at": 1724751600, "id_token": "eyJhbGciOiJSUzI1NiIs…"
   }

Confidential clients may authenticate at the token endpoint with HTTP Basic (client_secret_basic) or form parameters (client_secret_post); both are accepted.

Token lifecycle

Refresh rotates with a hand-off window: exchanging a refresh token returns a new access + refresh pair, and the pair it replaces stays valid until the new access token is first used — a token response lost on the network cannot lock you out, because retrying the exchange with the old refresh token still works until then. From the first use of the new access token, the replaced pair is revoked and replaying its refresh token is refused (invalid_grant). Store the newest pair, always.

POST https://app.academyos.app/oauth/token
grant_type=refresh_token&refresh_token=…&client_id=…[&client_secret=…]

Revoke tokens you no longer need (sign-out, account unlink) via RFC 7009:

POST https://app.academyos.app/oauth/revoke
token=…&client_id=…[&client_secret=…]

Tokens are stored as SHA-256 digests, like every other credential we hold for you.

The resource API

Authorization: Bearer <access_token> against /api/oauth/v1. This is a third credential regime: partner API keys and AcademyOS mobile-app tokens are not accepted here, and OAuth tokens are not accepted on the partner API or the mobile API. Errors use the familiar shape:

{ "sub": "user_9tRk…", "email": "learner@example.com", "email_verified": true, "name": "Ada Learner" }

{
  "marketplace_enrollments": [
    {
      "kind": "purchase",
      "order_id": "mord_…", "order_status": "paid",
      "purchased_at": "2026-08-11T14:03:22Z", "granted_at": null,
      "product_id": "prod_…", "name": "Practical Math", "slug": "practical-math",
      "creator_name": "Creator One Studio", "cover_image_url": "https://…",
      "access_state": "active", "access_expires_at": "2026-09-10T14:03:22Z",
      "days_remaining": 14, "enrollment_status": "active"
    },
    {
      "kind": "grant",
      "order_id": null, "order_status": null,
      "purchased_at": null, "granted_at": "2026-08-12T09:00:00Z",
      "product_id": "prod_…", "name": "…", "slug": "…",
      "creator_name": "…", "cover_image_url": "https://…",
      "access_state": "active", "access_expires_at": null,
      "days_remaining": null, "enrollment_status": "active"
    }
  ]
}

What the learner sees and controls

• The consent screen is branded, localized (en/es/pt), and names both your application and your partner organisation.
• Learners review every app they have authorized under Settings → Authorized Apps, and can revoke one at any time. Revocation kills all your tokens for that learner at once; the next authorize round-trip starts from a fresh consent screen. Build for tokens dying at any moment — the 401 tells you to re-authorize.
• An AcademyOS administrator impersonating a learner cannot consent on their behalf; the flow refuses.

Kill switch, rate limits and the fine print

• Partner deactivation is total: authorize renders the standard OAuth error page, the token endpoint answers invalid_client, and every already-issued access/refresh token answers 401 invalid_token from the same moment. Reactivation restores tokens that haven't expired.
• /oauth/authorize is rate-limited per IP (default 30/min), /oauth/token per IP (default 60/min); 429 with a plain body. These bound credential-stuffing, not your legitimate traffic.
• Redirect URIs are exact-match and https-only outside development, except loopback-IP callbacks (http://127.0.0.1:<port>/…), whose port may vary at authorize time per RFC 8252. No wildcard URIs, no fragments.
• The authorize endpoint must be a top-level navigation — it depends on the learner's AcademyOS session cookie, which does not exist in cross-site iframe or fetch contexts.
• There is no token introspection endpoint; identity comes from the id_token and userinfo.

Integration checklist

1. Register your organisation and client in the developer portal; store the client_id (and one-shot client_secret, if confidential) in your secret manager.
2. Point an OIDC client library at https://app.academyos.app/.well-known/openid-configuration.
3. Send learners through authorize with PKCE + state + nonce; validate everything on the way back.
4. Key your accounts on sub. Treat email as display data unless email_verified is true.
5. Ask for enrollments:read only if you actually render the learner's courses.
6. Refresh proactively (access tokens live 2 hours), store the rotated pair, and treat any 401 as "send the learner through authorize again".
7. Revoke tokens on sign-out/unlink instead of letting them age out.

Run the example client

The AcademyOS repository ships a framework-free reference client at examples/oauth-client/app.rb that walks this whole page in a real browser: discovery, PKCE, the callback, the code exchange as a confidential client, id_token verification against the JWKS, the three resource calls, refresh rotation and revocation. Every page it renders prints the raw upstream responses, so it doubles as a debugging tool for your own integration.

cp .env.example .env   # ACADEMYOS_ISSUER, CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, SESSION_SECRET
ruby app.rb            # then open http://localhost:4567 and click "Sign in with AcademyOS"

Against a deployed AcademyOS the redirect URI must be https (or a loopback IP): put the client behind a tunnel such as cloudflared tunnel --url http://localhost:4567 and register the tunnel's callback URL. The README next to the script carries the evidence checklist we run ourselves.