Goiabada
Overview
Admin API 1.0.0
Section titled “Admin API 1.0.0”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 acceptauthserver:admin-readalongside the domain’s own scope, and writes accept the domain scope (authserver:manage-users,authserver:manage-clientsorauthserver:manage-settings).authserver:manageis accepted everywhere.getClientSecretis the one readauthserver:admin-readdoes not reach: it answers a credential, so it acceptsauthserver:manage-clientsorauthserver:manage.exportUserholds the user’s audit events, so it takesauthserver:manage-usersonly together withauthserver:manage-settings. A token from the client credentials flow is accepted here. - Account API (
/api/v1/account/*): Self-service account management. Requiresauthserver:manage-accountscope, and a token issued for a user: these operations resolve the acting user fromsub, so a client credentials token is refused with 403 anderror_codeUSER_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.
Authentication
Section titled “Authentication”BearerAuth
Section titled “BearerAuth”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
DPoPAuth
Section titled “DPoPAuth”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