Authentication API reference - Red Hat Ansible Automation Platform

Authentication endpoints

Authentication endpoints are mounted at /api/v1/auth (paths shown without the router prefix).

POST /auth/login

Authenticate with a username and password to receive a JWT access token.

Authentication: None required.

Table 1. Request fields
Field	Type	Required	Description
`username`	string	Yes	Username (case-insensitive)
`password`	string	Yes	Password

Response (200):

Table 2. POST /auth/login response fields
Field	Type	Description
`access_token`	string	ES256 JWT access token
`token_type`	string	Always`Bearer`
`expires_in`	integer	Access token lifetime in seconds

On success, the response also sets an ao_refresh_token HttpOnly cookie containing the refresh token.

Errors: 401 - Invalid username or password, or account is inactive.

POST /auth/refresh

Exchange a valid refresh token for a new access token. The refresh token is read from the ao_refresh_token HttpOnly cookie.

Authentication: Refresh token cookie required.

The refresh token is not rotated. The same refresh token remains valid for its full lifetime. Group memberships are refreshed from the database on each call.

Response (200): Same format as /auth/login.

Errors: 401 - Missing, invalid, or expired refresh token, or session revoked.

POST /auth/logout

Terminate the current session by revoking the refresh token. The cookie is cleared in the response. The associated access token remains valid until it expires (up to 15 minutes) because access tokens are stateless.

When RP-initiated logout is enabled for the session's identity provider, the response includes a redirect URL to the end-session endpoint.

Authentication: Refresh token cookie required.

Table 3. POST /auth/logout parameters
Parameter	Required	Description
`post_logout_redirect_uri`	No	URL to redirect to after the identity provider ends the session. Validated against CORS origins. Defaults to`APP_OIDC_POST_LOGOUT_REDIRECT_URI`.

Response (200):

Table 4. POST /auth/logout response fields
Field	Type	Description
`detail`	string	Always`"Successfully logged out"`
`redirect_url`	string	Identity provider end-session URL. Present only when RP-initiated logout is enabled and the end-session endpoint is resolved. The frontend navigates to this URL using`window.location.href`.
`auth_error`	string	Error message when RP-initiated logout is enabled but the end-session endpoint cannot be resolved. The user is logged out of automation orchestrator but not the identity provider.

Errors: 401 - Missing, invalid, or expired refresh token.

GET /auth/me

Return information about the authenticated user from the access token claims. No database lookup is performed.

Authentication: Bearer token required.

Table 5. GET /auth/me response fields
Field	Type	Description
`id`	string	User UUID
`username`	string	Username
`email`	string	Email address
`groups`	array of strings	Group memberships (default:`[]`)
`rp_logout_enabled`	boolean	Whether RP-initiated logout is enabled for the current session's identity provider.`false` for local authentication sessions.

Errors: 401 - Missing or invalid access token.

GET /auth/providers

List enabled identity providers for the login page. This is a public endpoint.

Authentication: None required.

Table 6. GET /auth/providers response fields
Field	Type	Description
`providers`	array	Enabled identity providers
`providers[].id`	string	Provider UUID
`providers[].name`	string	Provider display name
`providers[].provider_type`	string	Provider type (for example,`oidc`)

GET /auth/oidc/authorize

Initiate the OIDC authorization code flow. Redirects the browser to the identity provider's authorization endpoint.

Table 7. GET /auth/oidc/authorize parameters
Parameter	Required	Description
`provider_id`	Yes	UUID of the identity provider to use
`redirect_to`	No	URL to redirect to after successful login (validated against CORS origins)

Response: 302 redirect to the identity provider. On error, redirects to the login page with an auth_error query parameter.

GET /auth/oidc/callback

Handle the OIDC callback after the user authenticates at the identity provider. This endpoint exchanges the authorization code for tokens, validates the ID token, creates or maps a local user, and establishes a session.

Response: 302 redirect to the frontend with the ao_refresh_token cookie set. On error, redirects to the login page with an auth_error query parameter.

POST /auth/csrf_token

Return a CSRF form token derived from the session's CSRF seed cookie. Include the returned token in the X-CSRF-Token header on state-changing cookie-authenticated requests, specifically POST /api/v1/auth/refresh and POST /api/v1/auth/logout.

Authentication: Requires the ao_csrf_token HttpOnly cookie (set at login).

Table 8. POST /auth/csrf_token response fields
Field	Type	Description
`csrf_token`	string	Form token to include in the`X-CSRF-Token` header

Errors: 403 - CSRF cookie is missing (the user is not authenticated through the cookie flow).

Session revocation endpoints

Session revocation endpoints are mounted at /api/v1/admin/revocation. Use these endpoints to terminate active sessions when you suspect a compromised account, when a user leaves the organization, or when you need permission changes to take effect immediately.

All revocation operations are recorded as security audit events.

GET /admin/revocation

Return the current global revocation timestamp. All tokens issued before this timestamp are treated as invalid.

Authentication: Bearer token required.

Authorization: admin:revocation:read permission (admin and auditor roles).

Table 9. GET /admin/revocation response fields
Field	Type	Description
`revoked_before`	string (ISO 8601) or null	Tokens issued before this timestamp are invalid. Null if no global revocation has been set.
`updated_at`	string (ISO 8601) or null	When the global revocation timestamp was last changed.
`updated_by`	string or null	Username of the administrator who set the timestamp.

POST /admin/revocation

Revoke all sessions globally by setting the global revocation timestamp to the current time. All tokens issued before this timestamp are treated as invalid, forcing all users to re-authenticate.

Authentication: Bearer token required.

Authorization: admin:revocation:execute permission (admin role only).

Table 10. POST /admin/revocation response fields
Field	Type	Description
`message`	string	Confirmation message with the revocation timestamp.

Behavior: After revocation, existing access tokens are treated as stale on the next verification. The global revocation timestamp is cached for up to 5 seconds, so a brief window exists before all nodes enforce the new timestamp.

POST /admin/revocation/users/{username}

Revoke all sessions for a specific user and increment the user's token version. The user must re-authenticate on their next request.

Authentication: Bearer token required.

Authorization: admin:revocation:execute permission (admin role only).

Table 11. POST /admin/revocation/users/{username} path parameters
Parameter	Type	Required	Description
`username`	string (path)	Yes	Username of the target user (case-insensitive).

Table 12. POST /admin/revocation/users/{username} response fields
Field	Type	Description
`message`	string	Confirmation message.
`sessions_revoked`	integer	Number of active sessions that were revoked.

Errors: 404 - User not found or has been deleted.

POST /admin/revocation/identity-providers/{idp_name}

Revoke all sessions that were authenticated through a specific identity provider. All users who signed in through this provider must re-authenticate.

Authentication: Bearer token required.

Authorization: admin:revocation:execute permission (admin role only).

Table 13. POST /admin/revocation/identity-providers/{idp_name} path parameters
Parameter	Type	Required	Description
`idp_name`	string (path)	Yes	Name of the identity provider.

Table 14. POST /admin/revocation/identity-providers/{idp_name} response fields
Field	Type	Description
`message`	string	Confirmation message.
`sessions_revoked`	integer	Number of active sessions that were revoked.

Errors: 404 - Identity provider not found or has been deleted.

Identity provider management endpoints

All identity provider endpoints are mounted at /api/v1/identity_providers.

Table 15. Identity provider management endpoints
Method	Path	Description
GET	`/`	List identity providers with filtering and pagination
POST	`/`	Create a new identity provider
GET	`/{provider_id}`	Get identity provider details
PATCH	`/{provider_id}`	Update an identity provider
DELETE	`/{provider_id}`	Delete an identity provider
POST	`/test`	Test an identity provider connection

Identity provider configuration fields

Table 16. Identity provider configuration fields
Field	Required	Default	Description
`provider_type`	Yes	-	Must be`oidc`
`idp_type`	No	-	Provider type hint:`aap` or`custom`
`auto_discovery`	No	`true`	Use`.well-known/openid-configuration` for endpoint discovery
`issuer_url`	Yes	-	OIDC issuer URL
`client_id`	Yes	-	OAuth 2.0 client ID
`client_secret`	Yes	-	OAuth 2.0 client secret (omit on PATCH to keep existing)
`redirect_uri`	Yes	-	Callback URL on automation orchestrator
`scopes`	No	`openid profile email`	Space-separated OAuth 2.0 scopes
`claim_mapping.subject`	No	`sub`	Claim for unique user identifier
`claim_mapping.email`	No	`email`	Claim for email address
`claim_mapping.username`	No	`preferred_username`	Claim for username
`claim_mapping.first_name`	No	`given_name`	Claim for first name
`claim_mapping.last_name`	No	`family_name`	Claim for last name
`group_jmespath_expression`	No	`groups[*]`	JMESPath expression to extract group values from token claims
`group_mapping_entries`	No	`[]`	Explicit IdP-to-Orchestrator group mappings
`group_mapping_entries[].idp_group_value`	Yes	-	Group value from the IdP token
`group_mapping_entries[].mapped_group_id`	Yes	-	UUID of the automation orchestrator group
`allow_all_authenticated`	No	`false`	Allow all users from this IdP to log in regardless of group mapping results
`aap_role_mapping_enabled`	No	`false`	Map the Ansible Automation Platform`aap_system_role` claim to built-in groups. Requires`idp_type` set to`aap`.
`enable_rp_initiated_logout`	No	`false`	Redirect users to the identity provider's end-session endpoint on logout
`end_session_endpoint`	No	`null`	OIDC end-session endpoint URL. If not set and`auto_discovery` is enabled, discovered from the provider's OIDC configuration.
`disable_tls_verify`	No	`false`	Disable TLS certificate verification for this identity provider. Use only for providers with self-signed or internal certificates.

When auto_discovery is disabled, you must also provide authorization_endpoint, token_endpoint, and jwks_uri. The userinfo_endpoint is optional.

Test connection response

Table 17. Test connection response fields
Field	Type	Description
`success`	boolean	Whether the connection test succeeded
`message`	string	Result message
`metadata`	object	Provider metadata (if available)
`claims_supported`	array	Claims supported by the provider
`claim_aliases`	object	Claim name aliases
`end_session_endpoint_supported`	boolean	Whether the identity provider advertises an end-session endpoint for RP-initiated logout

User management endpoints

All user endpoints are mounted at /api/v1.

Table 18. User management endpoints
Method	Path	Description
GET	`/users`	List users with pagination
POST	`/users`	Create a local user
GET	`/users/{user_id}`	Get user details
PATCH	`/users/{user_id}`	Update a user
DELETE	`/users/{user_id}`	Soft delete a user
GET	`/users/{user_id}/groups`	List user's group memberships
PUT	`/users/{user_id}/groups`	Set user's group memberships (replaces all)
GET	`/users/{user_id}/identities`	List user's identity provider links
POST	`/users/{user_id}/identities`	Attach an identity provider link to a user
DELETE	`/users/{user_id}/identities/{identity_id}`	Detach an identity provider link

Group management endpoints

Table 19. Group management endpoints
Method	Path	Description
GET	`/groups`	List groups with pagination
POST	`/groups`	Create a group
GET	`/groups/{group_id}`	Get group details
PATCH	`/groups/{group_id}`	Update a group
DELETE	`/groups/{group_id}`	Soft delete a group
GET	`/groups/{group_id}/members`	List group members
POST	`/groups/{group_id}/members`	Add a local user to a group
DELETE	`/groups/{group_id}/members/{user_id}`	Remove a user from a group

Token specifications

Access token

Table 20. Access token properties
Property	Value
Algorithm	ES256 (ECDSA P-256)
Default lifetime	15 minutes
Header`typ`	`at+jwt`
Header`kid`	Key ID of the signing key

Table 21. Access token claims
Claim	Type	Description
`sub`	string	User UUID
`iss`	string	Issuer (configured with`APP_JWT_ISSUER`)
`aud`	string	Audience (`orchestrator-api`)
`iat`	integer	Issued at (Unix timestamp)
`exp`	integer	Expiration (Unix timestamp)
`preferred_username`	string	Username
`email`	string	Email address
`name`	string	Display name
`groups`	array	Group memberships
`token_ver`	integer	Token version (for stale token detection)
`amr`	array	Authentication methods (for example,`["pwd"]` or`["fed"]`)
`idp`	string	Identity provider (for example,`local` or the provider name)

Refresh token

Table 22. Refresh token properties
Property	Value
Algorithm	ES256 (ECDSA P-256)
Default lifetime	8 hours
Delivery	`ao_refresh_token` HttpOnly cookie

Table 23. Refresh token claims
Claim	Type	Description
`sub`	string	User UUID
`jti`	string	Unique token identifier (session key in PostgreSQL)
`typ`	string	Always`refresh`
`iss`	string	Issuer
`aud`	string	Audience (`orchestrator-api`)
`iat`	integer	Issued at (Unix timestamp)
`exp`	integer	Expiration (Unix timestamp)

Error response format

All authentication errors use the RFC 9457 Problem Details format with content type application/problem+json:

{
  "type": "https://api.example.com/errors/unauthorized",
  "title": "Unauthorized",
  "detail": "Access token has expired",
  "code": "UNAUTHORIZED",
  "retryable": false,
  "instance": "/api/v1/auth/me"
}

Table 24. HTTP status codes
Status	When returned
401 Unauthorized	Missing credentials, invalid token, expired token, or revoked session
403 Forbidden	Valid authentication but insufficient permissions
403`ADMIN_MODIFY_FORBIDDEN`	Attempt to modify a built-in user account in a disallowed way
403`ADMIN_DELETE_FORBIDDEN`	Attempt to delete a built-in user account
403`ADMIN_DISABLE_NO_OTHER_ADMINS`	Attempt to disable the last enabled administrator
403`LAST_ADMIN_REMOVAL_FORBIDDEN`	Attempt to remove the last administrator from the built-in admins group
403`BUILTIN_GROUP_DELETE_FORBIDDEN`	Attempt to delete a built-in group
404 Not Found	User, group, or provider not found
409 Conflict	Name conflict or duplicate membership
401`ACCOUNT_DISABLED`	User account is disabled
503 Service Unavailable	Session store (PostgreSQL) is unreachable