Authentication

Overview

AWX supports multiple authentication methods for API access. All API requests must be authenticated unless accessing public endpoints.

Authentication Methods

AWX supports the following authentication methods based on the source code (awx/api/authentication.py):

1. Session Authentication

Session-based authentication using Django sessions. Primarily used by the web UI.

# Login to create session
curl -X POST \
  https://awx.example.com/api/login/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=secret" \
  -c cookies.txt

# Use session cookie for subsequent requests
curl -X GET \
  https://awx.example.com/api/v2/me/ \
  -b cookies.txt

2. Basic Authentication

HTTP Basic Authentication with username and password. Must be enabled via AUTH_BASIC_ENABLED setting.

curl -X GET \
  https://awx.example.com/api/v2/me/ \
  -u "admin:password"

Basic authentication must be enabled in AWX settings. It is logged for audit purposes.

3. OAuth 2.0 Token Authentication

The recommended method for API access using bearer tokens.

Create an OAuth Token

curl -X POST \
  https://awx.example.com/api/v2/users/1/personal_tokens/ \
  -u "admin:password" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "My API Token",
    "application": null,
    "scope": "write"
  }'

string

The bearer token to use for authentication

string

Token used to refresh the access token

string

Token expiration timestamp

Use the Token

curl -X GET \
  https://awx.example.com/api/v2/job_templates/ \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

4. Application OAuth Tokens

Create OAuth2 applications for third-party integrations.

Create an Application

curl -X POST \
  https://awx.example.com/api/v2/applications/ \
  -u "admin:password" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Application",
    "description": "Integration app",
    "client_type": "confidential",
    "authorization_grant_type": "password",
    "organization": 1
  }'

string

OAuth client identifier

string

OAuth client secret (confidential clients only)

Token Management

List Your Tokens

curl -X GET \
  https://awx.example.com/api/v2/users/1/personal_tokens/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Revoke a Token

curl -X DELETE \
  https://awx.example.com/api/v2/users/1/personal_tokens/123/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Token Scopes

Tokens can have different scopes:

read - Read-only access
write - Read and write access (default)

{
  "scope": "read"
}

Current User Information

Get information about the authenticated user:

curl -X GET \
  https://awx.example.com/api/v2/me/ \
  -H "Authorization: Bearer YOUR_TOKEN"

integer

User ID

string

Username

string

Email address

boolean

Whether user has superuser privileges

boolean

Whether user has system auditor role

POST /api/login/

Creates a session. Returns session cookie.

string

required

Username

string

required

Password

Logout

GET /api/logout/

Invalidates the current session.

Security Best Practices

Use OAuth Tokens

Prefer OAuth tokens over basic authentication. Tokens can be revoked and have expiration times.

Use HTTPS

Always use HTTPS in production to protect credentials and tokens in transit.

Rotate Tokens Regularly

Create new tokens periodically and revoke old ones to minimize security risks.

Use Limited Scopes

Use read-only tokens when write access is not needed.

Store Tokens Securely

Never commit tokens to source control. Use environment variables or secret management systems.

Authentication Errors

401 Unauthorized

Missing or invalid authentication credentials:

{
  "detail": "Authentication credentials were not provided."
}

403 Forbidden

Valid authentication but insufficient permissions:

{
  "detail": "You do not have permission to perform this action."
}

Example: Complete Authentication Flow

# 1. Create a personal access token
TOKEN_RESPONSE=$(curl -s -X POST \
  https://awx.example.com/api/v2/users/1/personal_tokens/ \
  -u "admin:password" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "API Access",
    "scope": "write"
  }')

# 2. Extract the token
TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.token')

# 3. Use the token for API requests
curl -X GET \
  https://awx.example.com/api/v2/job_templates/ \
  -H "Authorization: Bearer $TOKEN"

# 4. Verify current user
curl -X GET \
  https://awx.example.com/api/v2/me/ \
  -H "Authorization: Bearer $TOKEN"

Proxy and Gateway Authentication

AWX supports trusted proxy authentication via the X-Trusted-Proxy header for integration with authentication gateways. This is configured via REMOTE_HOST_HEADERS and PROXY_IP_ALLOWED_LIST settings.

Getting Started

Core Resources

Job Management

Advanced

Authentication

Overview

Authentication Methods

1. Session Authentication

2. Basic Authentication

3. OAuth 2.0 Token Authentication

Create an OAuth Token

Use the Token

4. Application OAuth Tokens

Create an Application

Token Management

List Your Tokens

Revoke a Token

Token Scopes

Current User Information

Logout

Security Best Practices

Authentication Errors

401 Unauthorized

403 Forbidden

Example: Complete Authentication Flow

Proxy and Gateway Authentication

​Overview

​Authentication Methods

​1. Session Authentication

​2. Basic Authentication

​3. OAuth 2.0 Token Authentication

​Create an OAuth Token

​Use the Token

​4. Application OAuth Tokens

​Create an Application

​Token Management

​List Your Tokens

​Revoke a Token

​Token Scopes

​Current User Information

​Login and Logout Endpoints

​Login

​Logout

​Security Best Practices

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​Example: Complete Authentication Flow

​Proxy and Gateway Authentication

Overview

Authentication Methods

1. Session Authentication

2. Basic Authentication

3. OAuth 2.0 Token Authentication

Create an OAuth Token

Use the Token

4. Application OAuth Tokens

Create an Application

Token Management

List Your Tokens

Revoke a Token

Token Scopes

Current User Information

Login and Logout Endpoints

Login

Logout

Security Best Practices

Authentication Errors

401 Unauthorized

403 Forbidden

Example: Complete Authentication Flow

Proxy and Gateway Authentication