Goiabada
Overview
Account API 1.0.0
Section titled “Account 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>getClientLogoImage, at /client/logo/{clientIdentifier} outside /api/v1, is
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. 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-cacheDo 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.
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, 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.
Security scheme type: http
Bearer format: JWT