Organizations and Teams

Organizations and teams are fundamental to AWX’s role-based access control (RBAC) system. Organizations serve as the basic unit of multi-tenancy, while teams group users for collaborative work.

Understanding Organizations

An Organization is the primary unit for dividing resources and permissions in AWX. Each organization can contain:

Projects
Inventories
Job Templates
Credentials
Teams
Users

Organization Roles

AWX provides several built-in roles for organizations:

Admin: Full control over the organization and all its resources
Auditor: Read-only access to the organization
Member: Basic participation permissions
Execute: Can run job templates in the organization
Project Admin: Manage projects within the organization
Inventory Admin: Manage inventories within the organization
Credential Admin: Manage credentials within the organization
Workflow Admin: Manage workflows within the organization
Job Template Admin: Manage job templates within the organization
Notification Admin: Manage notifications within the organization

Creating an Organization

Create via Web UI

Navigate to Organizations in the left sidebar and click Add. Fill in:

Name: Organization name (required)
Description: Optional description
Max Hosts: Maximum number of hosts (0 = unlimited)
Default Execution Environment: Optional default EE for jobs
Instance Groups: Assign instance groups for job execution

Create via API

Make a POST request to /api/v2/organizations/:

curl -X POST https://awx.example.com/api/v2/organizations/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "description": "Engineering team organization",
    "max_hosts": 100
  }'

Create via Ansible

Use the awx.awx.organization module:

- name: Create organization
  awx.awx.organization:
    name: Engineering
    description: Engineering team organization
    max_hosts: 100
    state: present
    controller_host: awx.example.com
    controller_username: admin
    controller_password: password

Managing Organization Access

Assigning Users to Organizations

Web UI
API
Ansible

Navigate to the organization
Click the Users tab
Click Add and select users
Assign appropriate roles

# Add user to organization with admin role
curl -X POST https://awx.example.com/api/v2/organizations/1/users/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": 5}'

# Grant admin role
curl -X POST https://awx.example.com/api/v2/organizations/1/roles/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user": 5, "role": "admin_role"}'

- name: Grant organization admin role
  awx.awx.role:
    user: john.doe
    target_team: Engineering
    role: admin
    state: present

Understanding Teams

A Team is a group of users that work on common projects within an organization. Teams:

Must belong to exactly one organization
Can be granted permissions on resources
Inherit organization-level permissions
Have unique names within their organization

Team Roles

Admin: Full control over the team
Member: Basic team membership
Read: View-only access to team details

Creating and Managing Teams

Create a Team

Web UI
API
Ansible

Navigate to Organizations → Select your organization
Click the Teams tab
Click Add
Enter team name and description
Click Save

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": "DevOps engineering team",
    "organization": 1
  }'

- name: Create a team
  awx.awx.team:
    name: DevOps Team
    description: DevOps engineering team
    organization: Engineering
    state: present

Add Users to Team

Web UI
API
Ansible

Navigate to the team
Click the Users tab
Click Add and select users
Assign member or admin roles

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

- name: Add user to team
  awx.awx.role:
    user: john.doe
    target_team: DevOps Team
    role: member
    state: present

Grant Team Permissions

Teams can be granted permissions on various resources:

- name: Grant team access to inventory
  awx.awx.role:
    team: DevOps Team
    inventory: Production
    role: use
    state: present

- name: Grant team access to job template
  awx.awx.role:
    team: DevOps Team
    job_template: Deploy Application
    role: execute
    state: present

Permission Inheritance

Permissions flow through the organization hierarchy:

Organization Admin
  ↓
Team Admin (inherits org permissions)
  ↓
Team Member (inherits team permissions)
  ↓
Resource Permissions (explicit grants)

Example Permission Flow

Organization Admin can manage all resources in the organization
Team Members inherit organization-level permissions
Explicit Resource Permissions can be granted to teams for specific inventories, projects, or job templates

Best Practices

Organize by Function

Create organizations based on business units or functions (e.g., Engineering, Operations, QA)

Use Teams for Projects

Create teams for specific projects or workstreams within an organization

Principle of Least Privilege

Grant only the minimum permissions necessary for users to perform their tasks

Regular Audits

Periodically review organization and team memberships to ensure they’re up to date

Common Use Cases

Multi-Environment Setup

# Organization for each environment
- name: Create environments
  awx.awx.organization:
    name: "{{ item }}"
    state: present
  loop:
    - Development
    - Staging
    - Production

# Teams within each environment
- name: Create environment teams
  awx.awx.team:
    name: "{{ item.team }}"
    organization: "{{ item.org }}"
    state: present
  loop:
    - { org: Development, team: Dev Team }
    - { org: Production, team: Ops Team }

Department-Based Organizations

- name: Create department organizations
  awx.awx.organization:
    name: "{{ item }}"
    max_hosts: 500
    state: present
  loop:
    - Engineering
    - Marketing
    - Finance

- name: Create functional teams
  awx.awx.team:
    name: "{{ item.name }}"
    organization: "{{ item.org }}"
    state: present
  loop:
    - { name: Backend Team, org: Engineering }
    - { name: Frontend Team, org: Engineering }
    - { name: Infrastructure Team, org: Engineering }

Viewing Organization Resources

List all resources in an organization via API:

# List organization projects
curl https://awx.example.com/api/v2/organizations/1/projects/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# List organization inventories
curl https://awx.example.com/api/v2/organizations/1/inventories/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# List organization teams
curl https://awx.example.com/api/v2/organizations/1/teams/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# List organization users
curl https://awx.example.com/api/v2/organizations/1/users/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Troubleshooting

Users can't see organization resources

Ensure users have been added to the organization with appropriate roles. Check:

User has organization member or higher role
User’s team has permissions on the resource
Resource is in the correct organization

Can't create resources in organization

Verify the user has admin permissions:

# Check user's organization roles
curl https://awx.example.com/api/v2/users/5/roles/ \
  -H "Authorization: Bearer YOUR_TOKEN" | \
  jq '.results[] | select(.summary_fields.resource_type == "organization")'

Team members can't execute job templates

Grant the team execute permission on the job template or ensure the team has organization execute role:

- name: Grant team execute access
  awx.awx.role:
    team: DevOps Team
    job_template: My Job
    role: execute
    state: present

RBAC Documentation

Learn more about AWX’s role-based access control system

Creating Projects

Create projects within your organization

Managing Inventories

Set up inventories for your teams

User Management

API reference for user management

Overview

Installation

Core Concepts

User Guide

Advanced Features

Integrations

Administration

Organizations and Teams

Understanding Organizations

Organization Roles

Creating an Organization

Managing Organization Access

Assigning Users to Organizations

Understanding Teams

Team Roles

Creating and Managing Teams

Permission Inheritance

Example Permission Flow

Best Practices

Organize by Function

Use Teams for Projects

Principle of Least Privilege

Regular Audits

Common Use Cases

Multi-Environment Setup

Department-Based Organizations

Viewing Organization Resources

Troubleshooting

RBAC Documentation

Creating Projects

Managing Inventories

User Management

​Understanding Organizations

​Organization Roles

​Creating an Organization

​Managing Organization Access

​Assigning Users to Organizations

​Understanding Teams

​Team Roles

​Creating and Managing Teams

​Permission Inheritance

​Example Permission Flow

​Best Practices

Organize by Function

Use Teams for Projects

Principle of Least Privilege

Regular Audits

​Common Use Cases

​Multi-Environment Setup

​Department-Based Organizations

​Viewing Organization Resources

​Troubleshooting

​Related Resources

RBAC Documentation

Creating Projects

Managing Inventories

User Management

Understanding Organizations

Organization Roles

Creating an Organization

Managing Organization Access

Assigning Users to Organizations

Understanding Teams

Team Roles

Creating and Managing Teams

Permission Inheritance

Example Permission Flow

Best Practices

Common Use Cases

Multi-Environment Setup

Department-Based Organizations

Viewing Organization Resources

Troubleshooting

Related Resources