Tokens

Token expiration

You can customize the expiration (in seconds) for access tokens and ID tokens on the Settings → Tokens page. These configurations apply globally to all clients. However, individual clients can override the global settings in their specific client configurations.

The default token expiration is set to 5 minutes. Access tokens are intentionally kept short-lived for security reasons.

OIDC claims in ID tokens

By default, Goiabada includes OpenID Connect scope claims (from profile, email, phone, address scopes) in ID tokens. This behavior matches industry standards (Auth0, Microsoft, Keycloak) and provides immediate access to user information without an additional API call.

However, you can configure this behavior globally or per-client to support different use cases:

Global configuration

Navigate to Settings → Tokens in the admin console:

Include OpenID Connect claims in ID tokens: Controls whether OIDC scope claims are included in ID tokens by default
Default: Enabled (claims included)
When disabled: Applications must use the /userinfo endpoint to retrieve user claims

Per-client configuration

In each client’s Tokens settings, you can override the global behavior:

Include OIDC claims in ID tokens: Three options
- Default - Use the global setting
- On - Always include claims in ID tokens for this client
- Off - Never include claims in ID tokens for this client

This per-client control allows you to:

Enable strict OIDC conformance for specific applications
Optimize token size for performance-critical applications
Meet different security requirements across your application portfolio

What’s always included

Regardless of this setting, ID tokens always contain:

Core OpenID claims: sub, iss, aud, exp, iat, auth_time, nonce, acr, amr
Goiabada-specific scopes (groups, attributes) follow their own inclusion rules

All claims are always available via the /userinfo endpoint, regardless of whether they’re included in the ID token.

OIDC specification compliance

According to OIDC Core 5.4, scope-related claims MAY be included in ID tokens but SHOULD be retrieved from the /userinfo endpoint for strict conformance.

For more details on this feature and when to use it, see OIDC claims in tokens.

Refresh tokens

Refresh tokens are used in the authorization code flow with PKCE (the client credentials flow doesn’t use refresh tokens).

Goiabada supports two types of refresh tokens: normal and offline.

Normal refresh tokens

Normal tokens are linked to the user session. They can be used to get a new access token as long as there’s an active user session.

When a normal refresh token is used, the user session last_accessed timestamp is bumped
The expiration time of a normal refresh token is the same as the user session idle timeout (default is 2 hours)
If the user session is terminated, it automatically invalidates the refresh tokens linked to that session

Offline refresh tokens

Offline refresh tokens are not linked to a user session. They can be used to obtain a new access token even when the user is not actively using the application.

Their expiration time is long (defaults to 30 days)
Useful for background tasks or applications that need to access resources on behalf of users without their immediate interaction

Requesting offline tokens

In your authorization request, when you ask for the offline_access scope, your refresh token will be classified as offline. Otherwise, if you don’t include the offline_access scope, your refresh token will be considered normal.

scope=openid offline_access

Refresh token rotation

Upon each usage of a refresh token, the refresh token passed to the /auth/token endpoint becomes inactive, and a new refresh token is provided in the token response.

In other words, a refresh token is a one-time-use token; once used, it must be substituted with the new refresh token obtained from the response.