Skip to content

Authentication

This page shows you how to get an access token for Goiabada’s APIs and call them with it.

Goiabada has two APIs, both served by the auth server:

  • The Admin API, under /api/v1/admin/, manages users, groups, clients, resources, permissions and settings. It’s the API the admin console itself calls. A service calls it with a token of its own.
  • The Account API, under /api/v1/account/, lets a signed-in user manage their own account: profile, email, password, two-factor authentication, sessions and consents. Your app calls it with the user’s token.

Every operation is in the Admin API and Account API reference, with a curl example.

A service that manages Goiabada on its own, with no user present, gets its token through the client credentials flow: it signs in as a client, with the client’s own permissions.

  1. In the admin console, open Admin, Clients and click New client. Enter a Client identifier, such as provisioning-service, turn on Client credentials, turn off Authorization code with PKCE, and click Create client.

  2. Click the new client’s identifier, open Authentication and copy the Client secret.

  3. Open Permissions, choose the authserver resource and the permission your service needs, such as manage-users, click Grant permission and then Save. Scopes explains what each permission allows.

  4. Get an access token, asking for the scope that matches the permission:

    Terminal window
    curl -X POST https://auth.example.com/auth/token \
    -d grant_type=client_credentials \
    -d client_id=provisioning-service \
    -d client_secret=YOUR_CLIENT_SECRET \
    -d scope=authserver:manage-users

    The answer carries the token in access_token, and its lifetime in seconds in expires_in.

  5. Call the API with the token in the Authorization header:

    Terminal window
    curl "https://auth.example.com/api/v1/admin/users/search?query=ana" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Ask for several scopes at once by separating them with spaces, as in scope=authserver:manage-users authserver:manage-clients. When the token expires, request a new one the same way.

Each of manage, admin-read, manage-users, manage-clients and manage-settings makes the client an administrator, so only an administrator holding authserver:manage can grant one. The administrator the setup created holds it.

The Account API acts on the account of the user the token was issued for, so it needs a token your app got for a signed-in user, through the authorization code flow. A token from the client credentials flow is refused, as below.

  1. Send the user to the authorization endpoint, asking for authserver:manage-account beside openid:

    GET https://auth.example.com/auth/authorize?client_id=my-app
    &redirect_uri=https://my-app.example.com/callback
    &response_type=code
    &scope=openid%20authserver:manage-account
    &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
    &code_challenge_method=S256
    &state=abc123

    The first time, the user sees the consent screen, which names your app and says what authserver:manage-account lets it do, and approves it. Their answer is kept, so each user is asked once.

  2. Exchange the code the user comes back with for tokens:

    Terminal window
    curl -X POST https://auth.example.com/auth/token \
    -d grant_type=authorization_code \
    -d client_id=my-app \
    -d client_secret=YOUR_CLIENT_SECRET \
    -d code=THE_CODE \
    -d redirect_uri=https://my-app.example.com/callback \
    -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
  3. Call the API with the access_token from the answer:

    Terminal window
    curl https://auth.example.com/api/v1/account/profile \
    -H "Authorization: Bearer USER_ACCESS_TOKEN"

Every user holds the manage-account permission from the moment they’re created, and it isn’t an administrative permission, so your client needs no permission of its own, and no allowance, to ask for it. What it needs is the user’s approval. The consent screen is shown the first time each user signs in to your app asking for authserver:manage-account, whatever your client’s Ask users for consent says, and again if they untick it or withdraw it under Account, Consents. Add sign-in to a web app covers the sign-in itself, PKCE included.

Until a user has approved it, your app can’t get the scope without them:

  • a prompt=none request asking for it is answered consent_required;
  • a refresh renewing it is refused with invalid_grant, and the refresh token isn’t spent, so a refresh whose scope leaves authserver:manage-account out still works.

A session or a live refresh token from an earlier authorization-code sign-in can encounter these checks until the user approves the scope. Send the user through an ordinary sign-in: they approve once, and the refreshes after it work. So do silent requests, unless your client is public with Remember consent off. Refresh tokens from the password grant don’t need this consent.

There are three ways, and which one fits depends on who’s making the change:

  • The Account API, with the user’s token. For an app that changes the signed-in user’s own account on their behalf. It asks for authserver:manage-account as above, and each user approves that on the consent screen: once, or at every sign-in for a public client with Remember consent off. The token reaches that user’s account and nothing else.
  • The Admin API, with your client’s own token. For a service that changes users’ accounts with no user present, such as provisioning from an HR system. It gets its token through the client credentials flow, as in Call the Admin API, holding authserver:manage-users, which only an administrator with authserver:manage can grant it. That makes the client an administrator, and it still can’t change an administrator.
  • A link to the admin console’s Account pages. For a change the user makes themselves. Link to /account/profile on the admin console, such as https://admin.example.com/account/profile. The user signs in there if they need to and edits their profile, email, phone, address, picture, password, two-factor authentication, sessions and consents. Your app needs no scope at all.

Every operation under /api/v1/ takes an access token in the Authorization header, as Bearer followed by the token.

The token must be an access token the auth server issued for the authserver resource, which is what asking for an authserver: scope gets you. An ID token or a refresh token is refused.

An access token bound to a key with DPoP goes with the DPoP scheme instead, beside a DPoP header carrying a new proof for the call:

Terminal window
curl https://auth.example.com/api/v1/account/profile \
-H "Authorization: DPoP USER_ACCESS_TOKEN" \
-H "DPoP: YOUR_PROOF"

The proof’s htu is the operation’s URL, such as https://auth.example.com/api/v1/account/profile,. Call userinfo and the API with a bound token has the rest.

The Admin API accepts a client’s token from the client credentials flow, and a user’s token from the authorization code flow when the client may request the administrative scopes on a user’s behalf.

The Account API accepts only a token issued for a user. A token from the client credentials flow is answered 403: with INSUFFICIENT_SCOPE when it doesn’t carry authserver:manage-account, which is the usual case, and with USER_CONTEXT_REQUIRED when its client was granted that permission.

Deleting the account, POST /api/v1/account/deletion, and downloading its data, GET /api/v1/account/export, accept only a token issued to the admin console’s own client. Any other client’s token is answered 403 with CLIENT_NOT_ALLOWED, whatever its scopes.

Downloading the account’s data also needs a recent sign-in: within the last 300 seconds, at urn:goiabada:level2_optional or above, so with the user’s authenticator code if they’ve set one up. The token’s auth_time and acr claims say when and how the user signed in, and a refreshed token keeps them from the sign-in it came from.

A token whose sign-in is older, or at urn:goiabada:level1, is answered 401 with INSUFFICIENT_USER_AUTHENTICATION and the step-up challenge of RFC 9470, which names the level and the age a new sign-in must meet:

WWW-Authenticate: Bearer realm="goiabada", error="insufficient_user_authentication",
error_description="This endpoint requires a more recent sign-in, or a stronger one.",
acr_values="urn:goiabada:level2_optional", max_age="300",
DPoP realm="goiabada", algs="ES256 ES384 ES512 PS256 PS384 PS512 RS256 RS384 RS512 Ed25519 EdDSA"

The admin console answers it by sending the user through the sign-in page again with prompt=login and that acr_values, and the token it gets back downloads.

Every token is checked against its client on every call, and a user’s token against the user and their session too, so it stops working before it expires once the client or the user is disabled, the session it was issued through ends, or it or its grant is revoked. The call is then answered 401 with INVALID_TOKEN.

Every 401 carries a WWW-Authenticate header with a Bearer challenge, then a DPoP challenge listing the proof algorithms, the error in the challenge of the scheme your call used. A 403 carries only that scheme’s challenge. The errors page lists every refusal, and the format of every error answer.

The auth server serves the whole API as an OpenAPI 3.0 document at /openapi.yaml, with no authentication:

Terminal window
curl https://auth.example.com/openapi.yaml

This reference is generated from it, so the two always say the same thing. Import it into Postman or Swagger UI, or generate a client from it.