REST API

Goiabada provides REST APIs for programmatic management of users, groups, clients, and settings. These APIs are used internally by the admin console but can also be called directly from your applications.

Overview

The auth server exposes two main API groups:

API	Required Scope	Purpose
Admin API `/api/v1/admin`	`authserver:manage` (or granular scopes)	Administrative control
Account API `/api/v1/account`	`authserver:manage-account`	Self-service account management

Granular Admin API scopes

Instead of granting full admin access with authserver:manage, you can use granular scopes to limit access to specific API domains:

Scope	Access Level	Endpoints
`authserver:admin-read`	Read-only	GET requests across all admin endpoints
`authserver:manage-users`	Full	Users, groups, permissions, sessions, consents
`authserver:manage-clients`	Full	OAuth2 clients and their configurations
`authserver:manage-settings`	Full	System settings, resources, and signing keys
`authserver:manage`	Full	All admin endpoints (backwards compatible)

Scope hierarchy

Read operations (GET): Allowed by authserver:admin-read, the domain-specific scope, or authserver:manage
Write operations (POST, PUT, DELETE): Require the domain-specific scope or authserver:manage

For example, to read user data you need any of:

authserver:admin-read
authserver:manage-users
authserver:manage

But to create or update a user, you need:

authserver:manage-users
authserver:manage

Authentication

All API endpoints require a valid JWT access token in the Authorization header:

Authorization: Bearer <access_token>

Setting up API access

Before you can call the REST APIs, you need to create a dedicated client and assign the appropriate permissions:

Step 1: Create a new client

Log into the admin console
Navigate to Clients and click Create new
Configure the client:
- Client identifier: Choose a meaningful name (e.g., api-client)
- Description: Describe the purpose (e.g., “Client for REST API access”)
- Enabled flow: Enable only Client credentials (you don’t need ‘Authorization code flow with PKCE’)
Save the client
Important: Go to the Authentication tab and copy the Client secret - you’ll need it for authentication

Step 2: Assign permissions

After creating the client, assign the required resource permissions:

Go to the Permissions tab of your client
For Admin API access:
- Select the authserver resource
- Assign the appropriate permission(s):
  - manage - Full access to all Admin API endpoints
  - admin-read - Read-only access to all Admin API endpoints
  - manage-users - Full access to user, group, and permission endpoints
  - manage-clients - Full access to client endpoints
  - manage-settings - Full access to settings and key endpoints
For Account API access (self-service endpoints):
- Select the authserver resource
- Assign the manage-account permission
- This allows users to manage their own accounts

Obtaining an access token

Once your client is configured with the required permissions, use the client credentials flow to obtain an access token:

curl -X POST https://auth.example.com/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret" \
  -d "scope=authserver:manage"

For granular access, request only the scopes you need:

# Read-only access to all admin endpoints
-d "scope=authserver:admin-read"

# Full access to user management only
-d "scope=authserver:manage-users"

# Multiple scopes (space-separated)
-d "scope=authserver:manage-users authserver:manage-clients"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 300
}

Use the access_token in the Authorization header for subsequent API calls.

OpenAPI Specification

Goiabada provides a complete OpenAPI 3.0 specification for the REST APIs, which you can use with tools like Swagger UI, Postman, or code generators.

Accessing the OpenAPI spec

The OpenAPI specification is available at:

GET https://auth.example.com/openapi.yaml

This endpoint is publicly accessible (no authentication required) and returns the complete API specification in YAML format.

Using the OpenAPI spec

You can use the specification with various tools:

Swagger UI: Import the URL to get an interactive API explorer
Postman: Import the OpenAPI spec to automatically generate a complete API collection
Code generation: Use tools like openapi-generator to generate client SDKs in your preferred language
API testing: Use the spec for automated API testing and validation

Error responses

All endpoints return errors in a consistent format:

{
  "error": {
    "message": "Human-readable error description",
    "code": "ERROR_CODE"
  }
}

Common error codes:

ACCESS_TOKEN_REQUIRED - Missing or invalid bearer token
INVALID_REQUEST_BODY - Malformed JSON in request
VALIDATION_ERROR - Input validation failed
NOT_FOUND - Resource not found
INTERNAL_SERVER_ERROR - Server-side error

Admin API

The Admin API provides administrative control over your Goiabada instance. Endpoints are organized by domain and support granular authorization:

Domain	Read Scope	Write Scope
Users, Groups, Permissions	`authserver:admin-read` or `authserver:manage-users`	`authserver:manage-users`
Clients	`authserver:admin-read` or `authserver:manage-clients`	`authserver:manage-clients`
Settings, Resources, Keys	`authserver:admin-read` or `authserver:manage-settings`	`authserver:manage-settings`

The authserver:manage scope grants full access to all domains (backwards compatible).

Users

Search users

GET /api/v1/admin/users/search?query=john&page=1&size=10

Query parameters:

Parameter	Type	Description
`query`	string	Search term (matches email, username, name)
`page`	int	Page number (default: 1)
`size`	int	Results per page (default: 10)

Response:

{
  "users": [
    {
      "id": 1,
      "email": "[email protected]",
      "emailVerified": true,
      "username": "johndoe",
      "givenName": "John",
      "familyName": "Doe",
      "enabled": true,
      "subject": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 10
}

Get user

GET /api/v1/admin/users/{id}

Returns complete user details including groups, permissions, and attributes.

Create user

POST /api/v1/admin/users/create

Request body:

{
  "email": "[email protected]",
  "emailVerified": false,
  "givenName": "New",
  "familyName": "User",
  "setPasswordType": "now",
  "password": "SecurePassword123!"
}

Field	Type	Required	Description
`email`	string	Yes	User’s email address
`emailVerified`	bool	No	Whether email is pre-verified
`givenName`	string	No	First name
`middleName`	string	No	Middle name
`familyName`	string	No	Last name
`setPasswordType`	string	No	`"now"` to set password immediately, `"email"` to send setup email
`password`	string	Conditional	Required if `setPasswordType` is `"now"`

Update user profile

PUT /api/v1/admin/users/{id}/profile

Request body:

{
  "username": "johndoe",
  "givenName": "John",
  "middleName": "",
  "familyName": "Doe",
  "nickname": "Johnny",
  "website": "https://johndoe.com",
  "gender": "male",
  "dateOfBirth": "1990-01-15",
  "zoneInfoCountryName": "United States",
  "zoneInfo": "America/New_York",
  "locale": "en-US"
}

Update user email

PUT /api/v1/admin/users/{id}/email

{
  "email": "[email protected]",
  "emailVerified": true
}

Update user phone

PUT /api/v1/admin/users/{id}/phone

{
  "phoneCountryUniqueId": "US",
  "phoneNumber": "5551234567",
  "phoneNumberVerified": false
}

Update user address

PUT /api/v1/admin/users/{id}/address

{
  "addressLine1": "123 Main St",
  "addressLine2": "Apt 4B",
  "addressLocality": "New York",
  "addressRegion": "NY",
  "addressPostalCode": "10001",
  "addressCountry": "US"
}

Update user password

PUT /api/v1/admin/users/{id}/password

{
  "newPassword": "NewSecurePassword123!"
}

Enable/disable user

PUT /api/v1/admin/users/{id}/enabled

{
  "enabled": false
}

Disable user OTP

PUT /api/v1/admin/users/{id}/otp

{
  "enabled": false
}

Delete user

DELETE /api/v1/admin/users/{id}

User attributes

Custom key-value attributes that can be included in tokens.

List user attributes

GET /api/v1/admin/users/{id}/attributes

Get attribute

GET /api/v1/admin/user-attributes/{id}

Returns a single user attribute by ID.

Create attribute

POST /api/v1/admin/user-attributes

{
  "userId": 1,
  "key": "department",
  "value": "Engineering",
  "includeInIdToken": true,
  "includeInAccessToken": false
}

Update attribute

PUT /api/v1/admin/user-attributes/{id}

Delete attribute

DELETE /api/v1/admin/user-attributes/{id}

User sessions

List user sessions

GET /api/v1/admin/users/{id}/sessions

Returns enhanced session details including device info, IP address, and validity status.

Get session

GET /api/v1/admin/user-sessions/{sessionIdentifier}

Returns details for a specific session by its session identifier.

Update session

PUT /api/v1/admin/user-sessions/{sessionIdentifier}

Updates session metadata (implementation specific).

Delete session

DELETE /api/v1/admin/user-sessions/{id}

Terminates a user session by ID.

User consents

List user consents

GET /api/v1/admin/users/{id}/consents

DELETE /api/v1/admin/user-consents/{id}

Groups

List groups

GET /api/v1/admin/groups

Returns all groups in the system.

Response:

{
  "groups": [
    {
      "id": 1,
      "groupIdentifier": "developers",
      "description": "Development team",
      "includeInIdToken": true,
      "includeInAccessToken": true,
      "memberCount": 5
    }
  ]
}

Search groups

GET /api/v1/admin/groups/search?query=dev

Search for groups by name or description.

Query parameters:

Parameter	Type	Description
`query`	string	Search term (matches group identifier and description)

Create group

POST /api/v1/admin/groups

{
  "groupIdentifier": "developers",
  "description": "Development team",
  "includeInIdToken": true,
  "includeInAccessToken": true
}

Get group

GET /api/v1/admin/groups/{id}

Update group

PUT /api/v1/admin/groups/{id}

Delete group

DELETE /api/v1/admin/groups/{id}

Group members

List members

GET /api/v1/admin/groups/{id}/members?page=1&size=10

Add member

POST /api/v1/admin/groups/{id}/members

{
  "userId": 1
}

Remove member

DELETE /api/v1/admin/groups/{id}/members/{userId}

User groups

Get user’s groups

GET /api/v1/admin/users/{id}/groups

Set user’s groups

PUT /api/v1/admin/users/{id}/groups

{
  "groupIds": [1, 2, 3]
}

Group attributes

Custom key-value attributes for groups that can be included in tokens.

List group attributes

GET /api/v1/admin/groups/{id}/attributes

Create group attribute

POST /api/v1/admin/group-attributes

{
  "groupId": 1,
  "key": "costCenter",
  "value": "CC-1234",
  "includeInIdToken": true,
  "includeInAccessToken": false
}

Update group attribute

PUT /api/v1/admin/group-attributes/{id}

Delete group attribute

DELETE /api/v1/admin/group-attributes/{id}

Resources

Resources represent APIs or services that can be protected with permissions.

List resources

GET /api/v1/admin/resources

Create resource

POST /api/v1/admin/resources

{
  "resourceIdentifier": "product-api",
  "description": "Product catalog API"
}

Get resource

GET /api/v1/admin/resources/{id}

Update resource

PUT /api/v1/admin/resources/{id}

Delete resource

DELETE /api/v1/admin/resources/{id}

Get resource permissions

GET /api/v1/admin/resources/{id}/permissions

Update resource permissions

PUT /api/v1/admin/resources/{id}/permissions

{
  "permissions": [
    {
      "permissionIdentifier": "read",
      "description": "Read access"
    },
    {
      "id": 5,
      "permissionIdentifier": "write",
      "description": "Write access (updated)"
    }
  ]
}

Permissions

Get user permissions

GET /api/v1/admin/users/{id}/permissions

Set user permissions

PUT /api/v1/admin/users/{id}/permissions

{
  "permissionIds": [1, 2, 3]
}

Get group permissions

GET /api/v1/admin/groups/{id}/permissions

Set group permissions

PUT /api/v1/admin/groups/{id}/permissions

{
  "permissionIds": [1, 2, 3]
}

Get users with permission

GET /api/v1/admin/permissions/{id}/users?page=1&size=10

Clients

OAuth2/OIDC client applications.

List clients

GET /api/v1/admin/clients

Create client

POST /api/v1/admin/clients

{
  "clientIdentifier": "my-web-app",
  "description": "My web application",
  "authorizationCodeEnabled": true,
  "clientCredentialsEnabled": false
}

Get client

GET /api/v1/admin/clients/{id}

Update client settings

PUT /api/v1/admin/clients/{id}

{
  "clientIdentifier": "my-web-app",
  "description": "Updated description",
  "enabled": true,
  "consentRequired": true,
  "defaultAcrLevel": "urn:goiabada:level1"
}

Update client authentication

PUT /api/v1/admin/clients/{id}/authentication

{
  "isPublic": false,
  "clientSecret": "new-secret-value"
}

Update OAuth2 flows

PUT /api/v1/admin/clients/{id}/oauth2-flows

{
  "authorizationCodeEnabled": true,
  "clientCredentialsEnabled": true
}

Update redirect URIs

PUT /api/v1/admin/clients/{id}/redirect-uris

{
  "redirectURIs": [
    "https://myapp.com/callback",
    "https://myapp.com/silent-refresh"
  ]
}

Update web origins

PUT /api/v1/admin/clients/{id}/web-origins

{
  "webOrigins": [
    "https://myapp.com"
  ]
}

Update token settings

PUT /api/v1/admin/clients/{id}/tokens

{
  "tokenExpirationInSeconds": 3600,
  "refreshTokenOfflineIdleTimeoutInSeconds": 2592000,
  "refreshTokenOfflineMaxLifetimeInSeconds": 31536000,
  "includeOpenIDConnectClaimsInAccessToken": "default"
}

Get client permissions

GET /api/v1/admin/clients/{id}/permissions

Set client permissions

PUT /api/v1/admin/clients/{id}/permissions

{
  "permissionIds": [1, 2, 3]
}

Get client sessions

GET /api/v1/admin/clients/{id}/sessions?page=1&size=10

Delete client

DELETE /api/v1/admin/clients/{id}

Settings

General settings

GET /api/v1/admin/settings/general
PUT /api/v1/admin/settings/general

{
  "appName": "My Auth Server",
  "issuer": "https://auth.example.com",
  "selfRegistrationEnabled": true,
  "selfRegistrationRequiresEmailVerification": true,
  "dynamicClientRegistrationEnabled": false,
  "passwordPolicy": "at_least_8_chars_one_number_one_uppercase_one_lowercase"
}

Email settings

GET /api/v1/admin/settings/email
PUT /api/v1/admin/settings/email

{
  "smtpEnabled": true,
  "smtpHost": "smtp.example.com",
  "smtpPort": 587,
  "smtpUsername": "[email protected]",
  "smtpPassword": "password",
  "smtpEncryption": "starttls",
  "smtpFromName": "My App",
  "smtpFromEmail": "[email protected]"
}

Send test email

POST /api/v1/admin/settings/email/send-test

{
  "to": "[email protected]"
}

Session settings

GET /api/v1/admin/settings/sessions
PUT /api/v1/admin/settings/sessions

{
  "userSessionIdleTimeoutInSeconds": 7200,
  "userSessionMaxLifetimeInSeconds": 86400
}

UI theme

GET /api/v1/admin/settings/ui-theme
PUT /api/v1/admin/settings/ui-theme

{
  "uiTheme": "dark"
}

Token settings

GET /api/v1/admin/settings/tokens
PUT /api/v1/admin/settings/tokens

{
  "tokenExpirationInSeconds": 300,
  "refreshTokenOfflineIdleTimeoutInSeconds": 2592000,
  "refreshTokenOfflineMaxLifetimeInSeconds": 31536000,
  "includeOpenIDConnectClaimsInAccessToken": false
}

Signing keys

GET /api/v1/admin/settings/keys

Returns all signing keys with their public key material in PEM and JWK formats.

POST /api/v1/admin/settings/keys/rotate

Rotates to a new signing key. The old key remains available for validation.

DELETE /api/v1/admin/settings/keys/{id}

Reference data

Phone countries

GET /api/v1/admin/phone-countries

Returns list of countries with calling codes for phone number validation.

Account API

The Account API provides self-service endpoints for authenticated users to manage their own account. All endpoints require the authserver:manage-account scope.

Profile

Get profile

GET /api/v1/account/profile

Returns the authenticated user’s complete profile.

Update profile

PUT /api/v1/account/profile

{
  "username": "johndoe",
  "givenName": "John",
  "middleName": "",
  "familyName": "Doe",
  "nickname": "Johnny",
  "website": "https://johndoe.com",
  "gender": "male",
  "dateOfBirth": "1990-01-15",
  "zoneInfoCountryName": "United States",
  "zoneInfo": "America/New_York",
  "locale": "en-US"
}

Email

Update email

PUT /api/v1/account/email

{
  "email": "[email protected]"
}

Send verification email

POST /api/v1/account/email/verification/send

No request body required. Returns:

{
  "emailVerificationSent": true,
  "emailDestination": "j***@example.com",
  "tooManyRequests": false,
  "waitInSeconds": 0,
  "emailVerified": false
}

Verify email

POST /api/v1/account/email/verification

{
  "verificationCode": "ABC123"
}

The verification code is 6 characters (3 letters + 3 numbers) and expires after 5 minutes.

Phone

Update phone

PUT /api/v1/account/phone

{
  "phoneCountryUniqueId": "US",
  "phoneNumber": "5551234567"
}

Send an empty phoneNumber to clear the phone number.

Address

Update address

PUT /api/v1/account/address

{
  "addressLine1": "123 Main St",
  "addressLine2": "Apt 4B",
  "addressLocality": "New York",
  "addressRegion": "NY",
  "addressPostalCode": "10001",
  "addressCountry": "US"
}

Password

Change password

PUT /api/v1/account/password

{
  "currentPassword": "OldPassword123!",
  "newPassword": "NewPassword456!"
}

Two-factor authentication (OTP)

Start OTP enrollment

GET /api/v1/account/otp/enrollment

Returns a QR code and secret key for TOTP setup:

{
  "base64Image": "data:image/png;base64,...",
  "secretKey": "JBSWY3DPEHPK3PXP"
}

Enable or disable OTP

PUT /api/v1/account/otp

Enable OTP:

{
  "enabled": true,
  "password": "CurrentPassword123!",
  "otpCode": "123456",
  "secretKey": "JBSWY3DPEHPK3PXP"
}

Disable OTP:

{
  "enabled": false,
  "password": "CurrentPassword123!"
}

Consents

List consents

GET /api/v1/account/consents

Returns all OAuth2 client consents granted by the user.

DELETE /api/v1/account/consents/{id}

Sessions

List sessions

GET /api/v1/account/sessions

Returns all active sessions with device info and validity status. Each session includes an isCurrent flag indicating if it’s the current session.

Terminate session

DELETE /api/v1/account/sessions/{id}

Logout

Request logout URL

POST /api/v1/account/logout-request

{
  "postLogoutRedirectUri": "https://myapp.com/logged-out",
  "state": "xyz123",
  "clientIdentifier": "my-app",
  "responseMode": "redirect"
}

Field	Type	Required	Description
`postLogoutRedirectUri`	string	Yes	URI to redirect after logout
`state`	string	No	State parameter (echoed back)
`clientIdentifier`	string	No	Client ID (auto-resolved if omitted)
`responseMode`	string	No	`"form_post"` or `"redirect"`

Response:

{
  "logoutUrl": "https://auth.example.com/auth/logout?id_token_hint=..."
}

Follow the logoutUrl to complete the logout process.

REST API

Overview

Granular Admin API scopes

Scope hierarchy

Authentication

Setting up API access

Step 1: Create a new client

Step 2: Assign permissions

Obtaining an access token

OpenAPI Specification

Accessing the OpenAPI spec

Using the OpenAPI spec

Error responses

Admin API

Users

Search users

Get user

Create user

Update user profile

Update user email

Update user phone

Update user address

Update user password

Enable/disable user

Disable user OTP

Delete user

User attributes

List user attributes

Get attribute

Create attribute

Update attribute

Delete attribute

User sessions

List user sessions

Get session

Update session

Delete session

User consents

List user consents

Revoke consent

Groups

List groups

Search groups

Create group

Get group

Update group

Delete group

Group members

List members

Add member

Remove member

User groups

Get user’s groups

Set user’s groups

Group attributes

List group attributes

Create group attribute

Update group attribute

Delete group attribute

Resources

List resources

Create resource

Get resource

Update resource

Delete resource

Get resource permissions

Update resource permissions

Permissions

Get user permissions

Set user permissions

Get group permissions

Set group permissions

Get users with permission

Clients

List clients

Create client

Get client

Update client settings

Update client authentication

Update OAuth2 flows