Skip to main content
theauth-go ships a complete OAuth 2.1 Authorization Server (AS) behind Config.AuthorizationServer. It is opt-in: callers who do not set this field get the v1.0 surface unchanged.

Wiring the AS

EncryptionKey is required when AuthorizationServer is set. It protects the Ed25519 signing key at rest.

Endpoints

Once AuthorizationServer is set, a.Mount(r) adds the endpoints below. They sit at the root of the router you pass in, not under /auth like the sign-in routes. A few things follow from that:
  • Call a.Mount on your top-level router. If you mount it on a sub-router, every URL below gets that prefix, and the URLs the server advertises in its metadata will not match.
  • Set Issuer to a bare origin such as https://as.example.com. The metadata route is registered only at the root, so an issuer with a path (https://example.com/tenant1) will not be discoverable.
To check a running server, fetch /.well-known/oauth-authorization-server. It lists the issuer and the full URL of every endpoint your configuration turned on.

Discovery

Clients and resource servers start here. The per-resource route only finds resources that live under the issuer’s own host. If your API runs somewhere else, such as https://api.example.com, serve its protected resource metadata from that host. The resource server package does this for you.

Getting a token

Enabled by configuration

Dynamic Client Registration

Agent identities and delegation

Add Config.AgentIdentity to enable agent CRUD and the delegation grant system:
Create an agent:

Trusted proxies

By default, X-Forwarded-For is not trusted. Enable it for specific proxy prefixes:

Key rotation

Signing keys rotate every 30 days. The JWKS endpoint always serves the current and one previous key so resource servers with a cached JWKS can verify tokens minted before the rotation. Call a.RotateSigningKey(ctx) to rotate ahead of schedule.

Admin surface for agents and delegations

When RBAC is enabled, the admin API gains org-scoped agent and delegation management:
These routes require the agents:admin and delegations:admin RBAC permissions respectively.

Next steps

Last modified on October 9, 2026