OAuth 2.0 quickstart for Cathopic connected apps - Help Center

Cathopic Connected Apps use OAuth 2.0 Authorization Code with mandatory PKCE S256. The same developer approval also unlocks Cathopic's commercial API, but OAuth connections use user tokens and the connected user's plan instead of API keys and metered API billing.

1. Get access and register the application

Submit the single developer access request through the contact form. After Cathopic approves the account by email, open Settings → Developer / API → OAuth applications, create the application, register its exact callbacks and required scopes, and store its one-time secret if it is confidential.

2. Discover the authorization server

GET https://cathopic.com/.well-known/oauth-authorization-server

3. Redirect the user

GET https://cathopic.com/oauth/authorize
    ?client_id=CLIENT_ID
    &redirect_uri=EXACT_CALLBACK
    &response_type=code
    &scope=account.read%20catalog.read%20entitlements.read%20licenses.create%20licenses.read
    &state=UNGUESSABLE_STATE
    &code_challenge=BASE64URL_SHA256_VERIFIER
    &code_challenge_method=S256
    &ui_locales=en

Build one URL; the line breaks only make the example readable. Generate new high-entropy state and PKCE values for every attempt. ui_locales is optional and can request a supported language such as en or es. If sign-in is required, Cathopic resumes the same authorization request and then shows the permission screen.

4. Validate the callback and exchange the code

Compare the returned state before exchanging the code. The redirect URI must match byte for byte.

POST https://cathopic.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=EXACT_CALLBACK&code=CODE&code_verifier=VERIFIER

Public applications omit client_secret. Store tokens and confidential secrets only on the server and encrypt them at rest. Access tokens last 30 minutes; refresh tokens last up to 30 days and rotate when used.

Common checks

A rejected callback usually differs from the registered URI by scheme, host, port, path, casing, or trailing slash.
invalid_request before consent means that PKCE S256, the challenge, or state is missing or invalid.
invalid_grant commonly means a code or rotated refresh token was reused, or the callback or verifier changed.
After a 401, refresh once; if refresh fails, ask the user to reconnect. A 403 means the token lacks the required scope.

See the complete OpenAPI contract and the detailed Connected Apps integration guide.