OAuth2 overview

Olympus uses Ory Hydra as its OAuth2 / OIDC server. Hydra implements the standard RFC 6749 (OAuth 2.0) and RFC 8252 (Native Apps) grants and the OpenID Connect 1.0 specification.

This page picks the right grant for your situation. The next pages walk through each grant end to end.

When to use which grant

Your application	Grant	Page
Server-side web app (you control the server, can keep a secret)	Authorization Code	Authorization Code
Single-page app (SPA), mobile app, CLI, anywhere a secret can't be kept	Authorization Code + PKCE	PKCE
Backend service calling another backend service (no human user involved)	Client Credentials	Client Credentials
Renewing a token without sending the user through login again	Refresh Token	Refresh Tokens
Discovering Olympus's OAuth2 endpoints programmatically	OIDC Discovery	OIDC Discovery
Getting profile data after login	OIDC `userinfo`	OIDC userinfo
Logging the user out of both your app and Olympus	RP-initiated logout	RP-initiated logout

What Olympus doesn't support

Implicit grant (response_type=token). Removed in OAuth 2.1; never enabled in Olympus. Use PKCE instead.
Password grant (grant_type=password). Removed in OAuth 2.1; never enabled in Olympus. Use Authorization Code instead.
Hybrid response types (response_type=code id_token). Not enabled by default. The standard Authorization Code flow returns the ID token from the /token endpoint, which is sufficient for almost every case.

Client types

Hydra classifies clients into two types based on whether they can keep a secret:

Confidential clients have a client secret. Server-side apps, M2M services. Authenticate to /oauth2/token via client_secret_basic or client_secret_post.
Public clients cannot keep a secret. SPAs, mobile apps, CLIs. Authenticate to /oauth2/token via PKCE (no secret).

Olympus enforces PKCE for all public clients. There is no way to disable this, see Security, PKCE Enforcement and ADR 0019.

Token types

Hydra issues three kinds of tokens:

Token	Format	Used for	TTL default
Access token	Opaque (default) or JWT	Calling APIs	1 hour
Refresh token	Opaque	Renewing access tokens	30 days (rotated on use)
ID token	JWT	Identity assertion (OIDC)	1 hour

Opaque access tokens must be introspected at /oauth2/introspect to resolve their claims. JWT access tokens can be validated locally if you fetch and trust the JWKS.

Olympus defaults to opaque access tokens because they're revocable without distributed cache invalidation. If you need JWT access tokens (for latency or cross-region reasons), configure your client with access_token_strategy=jwt, see the Hydra OAuth2 client reference.

Discovery

Every Olympus deployment exposes the standard OIDC discovery endpoint:

GET /.well-known/openid-configuration

Against the CIAM Hydra: http://localhost:3102/.well-known/openid-configuration Against the IAM Hydra: http://localhost:4102/.well-known/openid-configuration In production: https://ciam.your-domain/.well-known/openid-configuration

The response includes:

issuer, the canonical Hydra URL
authorization_endpoint, where to redirect users to start a flow
token_endpoint, where to exchange codes for tokens
userinfo_endpoint, where to get profile claims
jwks_uri, the JWKS for validating JWTs
revocation_endpoint
end_session_endpoint, RP-initiated logout
code_challenge_methods_supported, S256 only (Olympus rejects plain)

Use this endpoint to discover URLs at runtime, don't hard-code them.

Errors

OAuth2 errors come back as { error, error_description, error_uri } payloads per RFC 6749 §5.2 plus Olympus-specific extensions. See:

Where next

Authorization Code, most common flow.
PKCE, for SPAs, mobile, CLIs.
Client Credentials, server-to-server.
Your first OAuth2 client, five-minute end-to-end example.