> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ansible/awx/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials

> Manage AWX credentials via the API

## Overview

Credentials store authentication information for external services like cloud providers, SCM systems, machines, and vaults. Credential types define the schema for credential fields.

## Endpoints

| Method | Endpoint | Description |
| - | - | - |
| GET | `/api/v2/credentials/` | List credentials |
| POST | `/api/v2/credentials/` | Create credential |
| GET | `/api/v2/credentials/{id}/` | Retrieve credential |
| PATCH | `/api/v2/credentials/{id}/` | Update credential |
| DELETE | `/api/v2/credentials/{id}/` | Delete credential |
| POST | `/api/v2/credentials/{id}/copy/` | Copy credential |
| POST | `/api/v2/credentials/{id}/test/` | Test external credential |

## List Credentials

```bash theme={null}
curl -X GET \
  https://awx.example.com/api/v2/credentials/ \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Create Credential

```bash theme={null}
curl -X POST \
  https://awx.example.com/api/v2/credentials/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AWS Production",
    "description": "AWS credentials for production",
    "organization": 1,
    "credential_type": 3,
    "inputs": {
      "username": "AKIAIOSFODNN7EXAMPLE",
      "password": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    }
  }'
```

<ParamField body="name" type="string" required>
  Credential name
</ParamField>

<ParamField body="description" type="string">
  Credential description
</ParamField>

<ParamField body="organization" type="integer">
  Organization ID (null for personal credentials)
</ParamField>

<ParamField body="credential_type" type="integer" required>
  Credential type ID
</ParamField>

<ParamField body="inputs" type="object" required>
  Credential-specific input fields (varies by credential type)
</ParamField>

<Info>
  The `inputs` object structure depends on the credential type. Use OPTIONS or GET credential\_types to see required fields.
</Info>

## Retrieve Credential

```bash theme={null}
curl -X GET \
  https://awx.example.com/api/v2/credentials/5/ \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response Schema

<ResponseField name="id" type="integer">
  Credential ID
</ResponseField>

<ResponseField name="name" type="string">
  Credential name
</ResponseField>

<ResponseField name="description" type="string">
  Credential description
</ResponseField>

<ResponseField name="organization" type="integer">
  Organization ID (null for personal)
</ResponseField>

<ResponseField name="credential_type" type="integer">
  Credential type ID
</ResponseField>

<ResponseField name="managed" type="boolean">
  Whether credential is managed (read-only if true)
</ResponseField>

<ResponseField name="inputs" type="object">
  Credential inputs (sensitive fields are encrypted)
</ResponseField>

<ResponseField name="kind" type="string">
  Human-readable credential kind
</ResponseField>

<ResponseField name="cloud" type="boolean">
  Whether this is a cloud credential
</ResponseField>

<ResponseField name="kubernetes" type="boolean">
  Whether this is a Kubernetes credential
</ResponseField>

<ResponseField name="related" type="object">
  Links to related resources:

  * `organization` - Parent organization
  * `credential_type` - Credential type details
  * `owner_users` - Users who own this credential
  * `owner_teams` - Teams who own this credential
  * `activity_stream` - Activity log
  * `access_list` - Access list
  * `object_roles` - Available roles
  * `copy` - Copy endpoint
  * `input_sources` - Input sources for external credentials
</ResponseField>

## Update Credential

```bash theme={null}
curl -X PATCH \
  https://awx.example.com/api/v2/credentials/5/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "inputs": {
      "password": "newpassword"
    }
  }'
```

<Warning>
  Managed credentials cannot be modified.
</Warning>

## Delete Credential

```bash theme={null}
curl -X DELETE \
  https://awx.example.com/api/v2/credentials/5/ \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Credential Types

### List Credential Types

```bash theme={null}
curl -X GET \
  https://awx.example.com/api/v2/credential_types/ \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Common Credential Types

#### Machine (SSH)

```json theme={null}
{
  "credential_type": 1,
  "inputs": {
    "username": "ansible",
    "password": "secret",
    "ssh_key_data": "-----BEGIN RSA PRIVATE KEY-----...",
    "become_method": "sudo",
    "become_username": "root",
    "become_password": "rootpass"
  }
}
```

#### Source Control (Git/SVN)

```json theme={null}
{
  "credential_type": 2,
  "inputs": {
    "username": "git_user",
    "password": "git_token",
    "ssh_key_data": "-----BEGIN RSA PRIVATE KEY-----..."
  }
}
```

#### Amazon Web Services

```json theme={null}
{
  "credential_type": 3,
  "inputs": {
    "username": "AKIAIOSFODNN7EXAMPLE",
    "password": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "security_token": "temporary-token"
  }
}
```

#### Vault

```json theme={null}
{
  "credential_type": 6,
  "inputs": {
    "vault_password": "vaultpass",
    "vault_id": "dev"
  }
}
```

## Input Sources

### List Input Sources

```bash theme={null}
curl -X GET \
  https://awx.example.com/api/v2/credentials/5/input_sources/ \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Input sources fetch credential data from external systems (CyberArk, Thycotic, HashiCorp Vault, etc.).

## Test External Credential

```bash theme={null}
curl -X POST \
  https://awx.example.com/api/v2/credentials/5/test/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "secret_path": "/path/to/secret"
    }
  }'
```

## Owner Users

```bash theme={null}
curl -X GET \
  https://awx.example.com/api/v2/credentials/5/owner_users/ \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Owner Teams

```bash theme={null}
curl -X GET \
  https://awx.example.com/api/v2/credentials/5/owner_teams/ \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Object Roles

```bash theme={null}
curl -X GET \
  https://awx.example.com/api/v2/credentials/5/object_roles/ \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Available roles:

* **admin\_role** - Full credential administration
* **use\_role** - Use credential in jobs
* **read\_role** - View credential details

## Copy Credential

```bash theme={null}
curl -X POST \
  https://awx.example.com/api/v2/credentials/5/copy/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AWS Production Copy"
  }'
```

## Filtering

```bash theme={null}
# By name
?name__icontains=aws

# By organization
?organization=1

# By credential type
?credential_type=3

# Cloud credentials only
?cloud=true

# Kubernetes credentials
?kubernetes=true

# By kind
?kind=ssh
```

## Ordering

```bash theme={null}
# By name
?order_by=name

# By type
?order_by=credential_type__name

# By creation date
?order_by=-created
```

## Security

<AccordionGroup>
  <Accordion title="Encrypted Storage">
    All sensitive credential fields are encrypted in the database.
  </Accordion>

  <Accordion title="Display vs Storage">
    The API shows encrypted values as `$encrypted$`. Actual values are never returned.
  </Accordion>

  <Accordion title="Role-Based Access">
    Users need the `use` role to use credentials in jobs, and `admin` role to view/edit them.
  </Accordion>

  <Accordion title="Managed Credentials">
    System-managed credentials (`managed=true`) cannot be modified or deleted.
  </Accordion>
</AccordionGroup>

## Complete Example

```python theme={null}
import requests
import json

base_url = "https://awx.example.com/api/v2"
token = "YOUR_TOKEN"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Get machine credential type ID
types_response = requests.get(
    f"{base_url}/credential_types/?name=Machine",
    headers=headers
)
machine_type_id = types_response.json()['results'][0]['id']

# Create SSH credential
cred_data = {
    "name": "Production SSH",
    "description": "SSH access to production servers",
    "organization": 1,
    "credential_type": machine_type_id,
    "inputs": {
        "username": "ansible",
        "ssh_key_data": open('~/.ssh/id_rsa').read(),
        "become_method": "sudo"
    }
}

response = requests.post(
    f"{base_url}/credentials/",
    headers=headers,
    data=json.dumps(cred_data)
)

if response.status_code == 201:
    cred = response.json()
    print(f"Created credential {cred['id']}")
    print(f"Inputs (encrypted): {cred['inputs']}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.