Skip to content

Overview

The REST API of the Goiabada auth server.

Authentication

Every operation under /api/v1 requires a valid JWT access token in the Authorization header:

Authorization: Bearer <access_token>

An access token bound to a DPoP key (RFC 9449), one whose cnf.jkt claim is set, is sent with the DPoP scheme instead, beside a DPoP header carrying a proof for the request:

Authorization: DPoP <access_token>
DPoP: <proof>

getClientLogoImage, at /client/logo/{clientIdentifier}, getPublicSettings, at /api/public/settings, and a brand’s stylesheets and assets, getBrandStylesheet, getBrandColorsStylesheet and getBrandAssetFile, are outside /api/v1: they are public and marked security: [].

API Groups

  • Admin API (/api/v1/admin/*): administrative control. Each operation accepts any one of a small set of scopes rather than a single one: reads accept authserver:admin-read alongside the domain’s own scope, and writes accept the domain scope (authserver:manage-users, authserver:manage-clients or authserver:manage-settings). authserver:manage is accepted everywhere. getClientSecret is the one read authserver:admin-read does not reach: it answers a credential, so it accepts authserver:manage-clients or authserver:manage. exportUser holds the user’s audit events, so it takes authserver:manage-users only together with authserver:manage-settings. A token from the client credentials flow is accepted here.
  • Account API (/api/v1/account/*): Self-service account management. Requires authserver:manage-account scope, and a token issued for a user: these operations resolve the acting user from sub, so a client credentials token is refused with 403 and error_code USER_CONTEXT_REQUIRED.

Caching

Every response from an operation in either API group carries these headers, error responses and the token and scope refusals included:

Cache-Control: no-store
Pragma: no-cache

Do not cache these responses. Two operations return a credential in the body: getClientSecret returns the client secret decrypted, and getAccountOTPEnrollment returns a new authenticator’s setup key. The bearer token on the request does not make a cached copy safe: a private cache may still store a response it authenticated.

A few responses under these paths are answered before an operation is selected and carry neither header: a CORS preflight, and the errors returned when the server cannot read its own settings or the caller’s session. None of them carries a credential, and none of them is described by this document.

The headers are not declared per operation, since every operation sends them.

Information

  • License: MIT
  • OpenAPI version: 3.0.3

JWT access token.

Admin API: any one of authserver:admin-read, the domain scope for the operation (authserver:manage-users, authserver:manage-clients, authserver:manage-settings) or authserver:manage. A client credentials token is accepted. Reads accept authserver:admin-read, except getClientSecret; writes need the domain scope. exportUser takes authserver:manage-users only together with authserver:manage-settings.

The granular scopes stop short of administrators. An administrator is a user, group or client holding any of the six administrative permissions on the authserver resource (manage, admin-read, manage-users, manage-clients, manage-settings, browser-sessions), a user directly or through any of its groups, the admin console’s own client whatever it holds, and a client allowed to request the administrative scopes. Only authserver:manage creates an administrator, changes one, or changes what reaches one: a granular scope reaching an operation is still refused, with 403 MANAGE_SCOPE_REQUIRED, when the request grants or revokes an administrative permission (directly, or by moving a user into or out of a group holding one, or by deleting such a group), writes to an administrator, switches whether a client may request the administrative scopes, reads an administrator client’s secret, adds the authserver resource to a client’s introspection resources, reads or sets the secret of a client listed for it, sets or changes a client’s back-channel logout URI, changes the email or audit-log settings, or changes an administrative permission’s description. It keeps full control of everyone else, and still reads administrators. authserver:manage alone meets 409 LAST_ADMINISTRATOR, on the operations that could leave no enabled user holding it.

Account API: scope authserver:manage-account, on a token issued for a user. A client credentials token carries no auth_time claim and is refused with 403 USER_CONTEXT_REQUIRED.

Browser sessions: scope authserver:browser-sessions, and only that scope. It is deliberately not one of the manage-* scopes, so holding the admin console’s client secret is not a way to drive the admin API with no user present.

A token bound to a DPoP key is refused here with 401 INVALID_TOKEN: send it with the DPoP scheme.

Security scheme type: http

Bearer format: JWT

JWT access token bound to a DPoP key (RFC 9449), sent as Authorization: DPoP <access_token> beside a DPoP header holding one proof for the request. It takes the same scopes as BearerAuth.

The proof’s htm is the request’s method, its htu the auth server’s public base URL followed by the operation’s path, its ath the base64url SHA-256 hash of the access token, and its iat within 60 seconds of the auth server’s clock. It is signed by the key whose thumbprint is the token’s cnf.jkt. Each proof is accepted once. No nonce is needed.

A missing, repeated, invalid or replayed proof is refused with 401 INVALID_DPOP_PROOF. A proof by another key, or a token bound to no key, is refused with 401 INVALID_TOKEN.

Security scheme type: http

Bearer format: JWT