OAuth 2.0 apps — Hypery Docs

Third-party apps use OAuth 2.0 with PKCE support. Users approve scopes in the hub; your app receives an authorization code on the redirect URI, then exchanges it for access_token and refresh_token. Use the access token as Authorization: Bearer on /api/v1/* and management routes. For a React app with prebuilt modals and token handling, see React client — auth & modals.

Endpoints

Step	Method	URL
Authorize (browser redirect)	`GET`	`https://hypery.ai/api/oauth/authorize`
Token exchange / refresh	`POST`	`https://hypery.ai/api/oauth/token`

(Replace the host with your hub URL in development, e.g. http://localhost:3001.)

Authorize — query parameters

Parameter	Required	Description
`client_id`	Yes	OAuth client id from the registered app
`response_type`	Yes	Must be `code`
`redirect_uri`	Yes	Must match a URI registered on the app
`scope`	Yes	Space-separated scopes (e.g. `read write ai:chat billing:read`)
`state`	Recommended	Opaque value to prevent CSRF; returned on redirect
`code_challenge`	For PKCE	SHA-256 challenge
`code_challenge_method`	With PKCE	`S256` or `plain`

Success redirects to redirect_uri?code=...&state=....

Token — JSON body

Authorization code

Field	Required	Description
`grant_type`	Yes	`authorization_code`
`code`	Yes	Code from the redirect
`client_id`	Yes	Same as authorize
`redirect_uri`	Yes	Same as authorize
`client_secret`	For confidential clients	App secret
`code_verifier`	For PKCE	Original verifier

Refresh token

Field	Required
`grant_type`	`refresh_token`
`refresh_token`	Yes
`client_id`	Yes
`client_secret`	If confidential

Client id/secret may also be supplied via HTTP Basic on the token request.

Example token response (success)

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "scope": "read write ai:chat"
}

Code examples

// 1) Send the user to authorize (browser)
const u = new URL('https://hypery.ai/api/oauth/authorize');
u.searchParams.set('client_id', 'YOUR_CLIENT_ID');
u.searchParams.set('redirect_uri', 'https://yourapp.com/callback');
u.searchParams.set('response_type', 'code');
u.searchParams.set('scope', 'read write ai:chat billing:read');
u.searchParams.set('state', crypto.randomUUID());
window.location.href = u.toString();
 
// 2) On your server, exchange the code
const tokenRes = await fetch('https://hypery.ai/api/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: authorizationCodeFromQuery,
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    redirect_uri: 'https://yourapp.com/callback',
  }),
});
const tokens = await tokenRes.json();

import requests
 
r = requests.post(
    "https://hypery.ai/api/oauth/token",
    json={
        "grant_type": "authorization_code",
        "code": authorization_code,
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "redirect_uri": "https://yourapp.com/callback",
    },
)
tokens = r.json()

curl -sS 'https://hypery.ai/api/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "code": "CODE_FROM_REDIRECT",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://yourapp.com/callback"
  }'

Next steps

React client example

@hyperyai/sdk, AuthModal, RestrictionModal

Scopes

Permission scopes (ai:embeddings, ai:audio, …)