Skip to main content

​
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"
  }'
​
token
string
The bearer token to use for authentication
​
refresh_token
string
Token used to refresh the access token
​
expires
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
  }'
​
client_id
string
OAuth client identifier
​
client_secret
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"
​
id
integer
User ID
​
username
string
Username
​
email
string
Email address
​
is_superuser
boolean
Whether user has superuser privileges
​
is_system_auditor
boolean
Whether user has system auditor role

​
Login and Logout Endpoints

​
Login

POST /api/login/
Creates a session. Returns session cookie.
​
username
string
required
Username
​
password
string
required
Password

​
Logout

GET /api/logout/
Invalidates the current session.

​
Security Best Practices

Prefer OAuth tokens over basic authentication. Tokens can be revoked and have expiration times.
Always use HTTPS in production to protect credentials and tokens in transit.
Create new tokens periodically and revoke old ones to minimize security risks.
Use read-only tokens when write access is not needed.
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us