how it works
authorize, exchange, act
authorize with consent
third-party apps send users to your authorize endpoint. a consent screen shows exactly which scopes they’re granting before anything is issued.
exchange the code
the app trades the authorization code for tokens using pkce, so a code_verifier — not a shared secret in the browser — proves the request is legit.
call on the user’s behalf
with the returned token the app calls the gateway scoped to what the user allowed — ai:chat, ai:models, billing:read — and you can revoke it anytime.
token exchange
trade a code for scoped access
after the consent screen, the third-party app swaps its authorization code and pkce verifier for an access token — then calls the gateway with only the scopes the user granted.
- authorize, token, and revoke endpoints
- pkce + refresh tokens for public clients
- hosted consent screen with per-scope disclosure
- seven scopes from read to ai:chat to billing:read
// callback.ts — exchange the code for tokensconst res = await fetch("https://hypery.ai/api/oauth/token", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ grant_type: "authorization_code", code, code_verifier: verifier, client_id, redirect_uri, }),}) const { access_token } = await res.json()faq
questions
which oauth flows are supported?
the authorization code flow with pkce and refresh tokens, plus authorize, token, and revoke endpoints and a hosted consent screen. it’s standard oauth 2.0, so existing clients just work.
what scopes can other apps request?
seven scopes: read, write, ai:chat, ai:completions, ai:models, ai:images, and billing:read. the consent screen shows each requested scope so users grant exactly what they intend.
can users revoke access later?
yes. a revoke endpoint invalidates a token, and refresh tokens keep long-lived sessions alive until revoked, so users and admins stay in control of third-party access.
do i need pkce?
for public clients, yes — the token exchange takes a code_verifier that pairs with the challenge sent at authorize time, so intercepted codes can’t be redeemed by an attacker.