Skip to content

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.

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).

  • Authorization code, with PKCE required for public clients and optional for confidential clients. The authorize request carries code_challenge and code_challenge_method; the token request carries code_verifier.
  • Refresh token rotation. A refresh_token grant 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.

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.

  • Missing PKCE on the authorize step. For a public client the authorize request is rejected if it has no code_challenge; code_challenge and code_challenge_method must 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_grant and 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.