OAuth / OIDC

These endpoints are provided by Better Auth. They follow standard OAuth 2.1 and OIDC protocols.

OIDC Discovery

GET /.well-known/openid-configuration

Returns standard OIDC discovery document with issuer, authorization endpoint, token endpoint, JWKS URI, and supported scopes.

JWKS

GET /api/auth/jwks

Returns the public key set used to verify JWT signatures. Each SaaS backend fetches this to verify access tokens locally.

Authorization

GET /api/auth/oauth2/authorize
  ?response_type=code
  &client_id=scli_xxx
  &redirect_uri=https://tobby.example.com/callback
  &scope=openid+profile+offline_access
  &state=xxx
  &code_challenge=xxx
  &code_challenge_method=S256
  &resource=tobby-api

Standard OAuth 2.1 Authorization Code flow with PKCE. The resource parameter specifies the desired audience for the access token.

Token

POST /api/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
code=xxx
redirect_uri=xxx
client_id=scli_xxx
code_verifier=xxx           (public client)
client_secret=xxx           (confidential client)
resource=tobby-api           (audience)

Response

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "openid profile offline_access"
}

Token Refresh

POST /api/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
refresh_token=xxx
client_id=scli_xxx

JWT Payload

{
  "iss": "https://auth.example.com",
  "sub": "user_abc123",
  "aud": "tobby-api",
  "azp": "tobby-web",
  "scope": "openid profile offline_access",
  "iat": 1680000000,
  "exp": 1680086400,
  "app_user": {
    "id": "au_def456",
    "status": "active",
    "role": "member"
  }
}

Verification Requirements

Each SaaS backend MUST verify:

Claim	Check
iss	Matches saas-core’s issuer URL
aud	Matches the application’s own audience
exp	Token is not expired
Signature	RS256 signature matches JWKS public key