OAuth
The OAuth API is the OAuth 2.0 / OpenID Connect surface for token issuance, refresh, and revocation. The authorization endpoint lives on the auth service; the token, user-info, and revocation endpoints live on the public API.
For the conceptual overview of how OAuth fits into Skynet — grant types, scopes, client registration, personal API tokens — see Auth. This page covers the endpoints themselves.
Endpoints at a glance
Section titled “Endpoints at a glance”| Endpoint | Purpose |
|---|---|
GET https://auth.skynetgo.org/authorize |
Start the authorization-code flow (served by the auth service) |
POST /oauth2/token |
Exchange an authorization code (grant_type=authorization_code) or a refresh token (grant_type=refresh_token) for tokens |
GET /oauth2/userinfo |
OpenID Connect claims for the bearer’s user (sub, email, name, preferred_username, roles) |
POST /oauth/revoke |
Revoke the presented bearer token and, for a user token, the user’s whole grant to that client |
GET /.well-known/openid-configuration |
OpenID Connect discovery document |
GET /.well-known/jwks.json |
Public keys that verify id_token signatures |
There is no token-introspection endpoint. A user disconnects a third-party app with DELETE /v1/me/connected-apps/{clientId} (list them with GET /v1/me/connected-apps).
Supported flows
Section titled “Supported flows”- Authorization code, with PKCE required for public clients and optional for confidential clients. The authorize request carries
code_challengeandcode_challenge_method; the token request carriescode_verifier. - Refresh token rotation. A
refresh_tokengrant returns a new refresh token and retires the old one. Always replace the stored refresh token with the new one.
There is no client_credentials, password, or implicit grant. See Auth — Grant types.
Client identifiers
Section titled “Client identifiers”Every token-endpoint call carries client_id. Confidential clients also authenticate with their client_secret, either in the form body or with HTTP Basic auth; public clients omit it and rely on PKCE.
Common pitfalls
Section titled “Common pitfalls”- Missing PKCE on the authorize step. For a public client the authorize request is rejected if it has no
code_challenge;code_challengeandcode_challenge_methodmust be sent together. - Reusing an authorization code. Codes are single-use and expire after 10 minutes; trying to reuse one returns 400 with
{"detail": "Invalid authorization code"}. - Refresh token rotation. When refresh returns a new refresh token, replace the stored copy immediately. Replaying a rotated refresh token is tolerated only for a short grace window (meant for a lost response); after that it fails with
invalid_grantand the user must sign in again. - Error shape. Token-endpoint errors mostly follow RFC 6749 (
{"error": ..., "error_description": ...}); a rejected authorization code or PKCE verifier comes back as a 400 with the API’s usual{detail}envelope instead. Handle both.