Teams

Overview

Teams provide a way to group users and assign permissions collectively within an organization. Teams belong to an organization and can be granted roles on various resources.

Endpoints

Method	Endpoint	Description
GET	`/api/v2/teams/`	List teams
POST	`/api/v2/teams/`	Create team
GET	`/api/v2/teams/{id}/`	Retrieve team
PATCH	`/api/v2/teams/{id}/`	Update team
DELETE	`/api/v2/teams/{id}/`	Delete team

List Teams

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

Create Team

curl -X POST \
  https://awx.example.com/api/v2/teams/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DevOps Team",
    "description": "Infrastructure and deployment team",
    "organization": 1
  }'

name

string

required

Name of the team (unique within organization)

description

string

Team description

organization

integer

required

ID of the parent organization

Retrieve Team

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

Response Schema

integer

Team ID

name

string

Team name

description

string

Team description

organization

integer

Parent organization ID

created

string

Creation timestamp (ISO 8601)

modified

string

Last modification timestamp

Links to related resources:

organization - Parent organization
users - Team members
projects - Projects the team has access to
credentials - Credentials the team has access to
roles - Roles assigned to the team
object_roles - Object-level roles
activity_stream - Activity log
access_list - Access list

summary_fields

object

Summary information about the organization and related objects

Update Team

curl -X PATCH \
  https://awx.example.com/api/v2/teams/5/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated team description"
  }'

Delete Team

curl -X DELETE \
  https://awx.example.com/api/v2/teams/5/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Team Users

List Team Members

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

Add User to Team

curl -X POST \
  https://awx.example.com/api/v2/teams/5/users/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 10
  }'

integer

required

User ID to add to the team

Remove User from Team

curl -X POST \
  https://awx.example.com/api/v2/teams/5/users/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 10,
    "disassociate": true
  }'

Team Projects

List projects the team has access to:

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

Team Credentials

List credentials the team has access to:

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

Roles

List Team Roles

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

Shows all roles assigned to the team across all resources.

List Object Roles

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

Shows available roles that can be granted on the team itself:

member_role - Team membership
admin_role - Team administration

Grant Team Role on Resource

To grant a team role on a resource (e.g., project):

# 1. Get the role ID for the resource
curl -X GET \
  https://awx.example.com/api/v2/projects/7/object_roles/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# 2. Add the team to the role
curl -X POST \
  https://awx.example.com/api/v2/roles/{role_id}/teams/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 5
  }'

Activity Stream

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

Access List

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

Shows which users have access to the team and their roles.

Filtering

# By name
?name=DevOps

# By organization
?organization=1

# By organization name
?organization__name=Engineering

# Search
?search=devops

Ordering

# By name
?order_by=name

# By creation date
?order_by=-created

# By organization
?order_by=organization__name

Complete Example

import requests
import json

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

# Create team
team_data = {
    "name": "Backend Engineers",
    "description": "Backend development team",
    "organization": 1
}

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

if response.status_code == 201:
    team = response.json()
    team_id = team['id']
    print(f"Created team {team_id}")
    
    # Add users to team
    user_ids = [10, 11, 12]
    for user_id in user_ids:
        add_response = requests.post(
            f"{base_url}/teams/{team_id}/users/",
            headers=headers,
            data=json.dumps({"id": user_id})
        )
        if add_response.status_code == 204:
            print(f"Added user {user_id} to team")
    
    # List team members
    members = requests.get(
        f"{base_url}/teams/{team_id}/users/",
        headers=headers
    ).json()
    
    print(f"Team has {members['count']} members")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

Team Permissions Model

Teams provide an efficient way to manage permissions:

Create Team - Within an organization
Add Users - Add members to the team
Grant Roles - Assign roles on resources to the team
Inherit Permissions - All team members inherit the team’s permissions

This is more maintainable than assigning roles individually to users.

Best Practices

Use Descriptive Names

Name teams clearly to indicate their purpose:

“Production Deploy Team”
“Database Administrators”
“QA Automation Team”

Align with Organizations

Create teams that align with your organizational structure and match how you manage permissions.

Use Teams for Role Assignment

Prefer assigning roles to teams rather than individual users for easier management.

Document Team Purposes

Use the description field to document the team’s purpose and responsibilities.

Getting Started

Core Resources

Job Management

Advanced

Overview

Endpoints

List Teams

Create Team

Retrieve Team

Response Schema

Update Team

Delete Team

Team Users

List Team Members

Add User to Team

Remove User from Team

Team Projects

Team Credentials

Roles

List Team Roles

List Object Roles

Grant Team Role on Resource

Activity Stream

Access List

Filtering

Ordering

Complete Example

Team Permissions Model

Best Practices

Build docs developers (and LLMs) love

Getting Started

Core Resources

Job Management

Advanced

​Overview

​Endpoints

​List Teams

​Create Team

​Retrieve Team

​Response Schema

​Update Team

​Delete Team

​Team Users

​List Team Members

​Add User to Team

​Remove User from Team

​Team Projects

​Team Credentials

​Roles

​List Team Roles

​List Object Roles

​Grant Team Role on Resource

​Activity Stream

​Access List

​Filtering

​Ordering

​Complete Example

​Team Permissions Model

​Best Practices

Build docs developers (and LLMs) love

Overview

Endpoints

List Teams

Create Team

Retrieve Team

Response Schema

Update Team

Delete Team

Team Users

List Team Members

Add User to Team

Remove User from Team

Team Projects

Team Credentials

Roles

List Team Roles

List Object Roles

Grant Team Role on Resource

Activity Stream

Access List

Filtering

Ordering

Complete Example

Team Permissions Model

Best Practices