---
title: Roles
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: Docs > API Reference > Roles
---

# Roles

The Roles API is used to create and manage Datadog roles, what [global permissions](https://docs.datadoghq.com/account_management/rbac.md) they grant, and which users belong to them.

Permissions related to specific account assets can be granted to roles in the Datadog application without using this API. For example, granting read access on a specific log index to a role can be done in Datadog from the [Pipelines page](https://app.datadoghq.com/logs/pipelines).

Roles can also be managed in bulk through the Datadog UI, which provides the capability to assign a single permission to multiple roles simultaneously.

## List permissions →{% #list-permissions %}

| Datadog site      | API endpoint                                         |
| ----------------- | ---------------------------------------------------- |
| ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/permissions |
| ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/permissions |
| app.datadoghq.eu  | GET https://api.datadoghq.eu/api/v2/permissions      |
| app.ddog-gov.com  | GET https://api.ddog-gov.com/api/v2/permissions      |
| us2.ddog-gov.com  | GET https://api.us2.ddog-gov.com/api/v2/permissions  |
| app.datadoghq.com | GET https://api.datadoghq.com/api/v2/permissions     |
| us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/permissions |
| us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/permissions |

## List roles →{% #list-roles %}

| Datadog site      | API endpoint                                   |
| ----------------- | ---------------------------------------------- |
| ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/roles |
| ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/roles |
| app.datadoghq.eu  | GET https://api.datadoghq.eu/api/v2/roles      |
| app.ddog-gov.com  | GET https://api.ddog-gov.com/api/v2/roles      |
| us2.ddog-gov.com  | GET https://api.us2.ddog-gov.com/api/v2/roles  |
| app.datadoghq.com | GET https://api.datadoghq.com/api/v2/roles     |
| us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/roles |
| us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/roles |

## Create role →{% #create-role %}

| Datadog site      | API endpoint                                    |
| ----------------- | ----------------------------------------------- |
| ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/roles |
| ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/roles |
| app.datadoghq.eu  | POST https://api.datadoghq.eu/api/v2/roles      |
| app.ddog-gov.com  | POST https://api.ddog-gov.com/api/v2/roles      |
| us2.ddog-gov.com  | POST https://api.us2.ddog-gov.com/api/v2/roles  |
| app.datadoghq.com | POST https://api.datadoghq.com/api/v2/roles     |
| us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/roles |
| us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/roles |

## Get a role →{% #get-a-role %}

| Datadog site      | API endpoint                                             |
| ----------------- | -------------------------------------------------------- |
| ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/roles/{role_id} |
| ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/roles/{role_id} |
| app.datadoghq.eu  | GET https://api.datadoghq.eu/api/v2/roles/{role_id}      |
| app.ddog-gov.com  | GET https://api.ddog-gov.com/api/v2/roles/{role_id}      |
| us2.ddog-gov.com  | GET https://api.us2.ddog-gov.com/api/v2/roles/{role_id}  |
| app.datadoghq.com | GET https://api.datadoghq.com/api/v2/roles/{role_id}     |
| us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/roles/{role_id} |
| us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/roles/{role_id} |

## Update a role →{% #update-a-role %}

| Datadog site      | API endpoint                                               |
| ----------------- | ---------------------------------------------------------- |
| ap1.datadoghq.com | PATCH https://api.ap1.datadoghq.com/api/v2/roles/{role_id} |
| ap2.datadoghq.com | PATCH https://api.ap2.datadoghq.com/api/v2/roles/{role_id} |
| app.datadoghq.eu  | PATCH https://api.datadoghq.eu/api/v2/roles/{role_id}      |
| app.ddog-gov.com  | PATCH https://api.ddog-gov.com/api/v2/roles/{role_id}      |
| us2.ddog-gov.com  | PATCH https://api.us2.ddog-gov.com/api/v2/roles/{role_id}  |
| app.datadoghq.com | PATCH https://api.datadoghq.com/api/v2/roles/{role_id}     |
| us3.datadoghq.com | PATCH https://api.us3.datadoghq.com/api/v2/roles/{role_id} |
| us5.datadoghq.com | PATCH https://api.us5.datadoghq.com/api/v2/roles/{role_id} |

## Delete role →{% #delete-role %}

| Datadog site      | API endpoint                                                |
| ----------------- | ----------------------------------------------------------- |
| ap1.datadoghq.com | DELETE https://api.ap1.datadoghq.com/api/v2/roles/{role_id} |
| ap2.datadoghq.com | DELETE https://api.ap2.datadoghq.com/api/v2/roles/{role_id} |
| app.datadoghq.eu  | DELETE https://api.datadoghq.eu/api/v2/roles/{role_id}      |
| app.ddog-gov.com  | DELETE https://api.ddog-gov.com/api/v2/roles/{role_id}      |
| us2.ddog-gov.com  | DELETE https://api.us2.ddog-gov.com/api/v2/roles/{role_id}  |
| app.datadoghq.com | DELETE https://api.datadoghq.com/api/v2/roles/{role_id}     |
| us3.datadoghq.com | DELETE https://api.us3.datadoghq.com/api/v2/roles/{role_id} |
| us5.datadoghq.com | DELETE https://api.us5.datadoghq.com/api/v2/roles/{role_id} |

## List permissions for a role →{% #list-permissions-for-a-role %}

| Datadog site      | API endpoint                                                         |
| ----------------- | -------------------------------------------------------------------- |
| ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/roles/{role_id}/permissions |
| ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/roles/{role_id}/permissions |
| app.datadoghq.eu  | GET https://api.datadoghq.eu/api/v2/roles/{role_id}/permissions      |
| app.ddog-gov.com  | GET https://api.ddog-gov.com/api/v2/roles/{role_id}/permissions      |
| us2.ddog-gov.com  | GET https://api.us2.ddog-gov.com/api/v2/roles/{role_id}/permissions  |
| app.datadoghq.com | GET https://api.datadoghq.com/api/v2/roles/{role_id}/permissions     |
| us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/roles/{role_id}/permissions |
| us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/roles/{role_id}/permissions |

## Grant permission to a role →{% #grant-permission-to-a-role %}

| Datadog site      | API endpoint                                                          |
| ----------------- | --------------------------------------------------------------------- |
| ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/roles/{role_id}/permissions |
| ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/roles/{role_id}/permissions |
| app.datadoghq.eu  | POST https://api.datadoghq.eu/api/v2/roles/{role_id}/permissions      |
| app.ddog-gov.com  | POST https://api.ddog-gov.com/api/v2/roles/{role_id}/permissions      |
| us2.ddog-gov.com  | POST https://api.us2.ddog-gov.com/api/v2/roles/{role_id}/permissions  |
| app.datadoghq.com | POST https://api.datadoghq.com/api/v2/roles/{role_id}/permissions     |
| us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/roles/{role_id}/permissions |
| us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/roles/{role_id}/permissions |

## Revoke permission →{% #revoke-permission %}

| Datadog site      | API endpoint                                                            |
| ----------------- | ----------------------------------------------------------------------- |
| ap1.datadoghq.com | DELETE https://api.ap1.datadoghq.com/api/v2/roles/{role_id}/permissions |
| ap2.datadoghq.com | DELETE https://api.ap2.datadoghq.com/api/v2/roles/{role_id}/permissions |
| app.datadoghq.eu  | DELETE https://api.datadoghq.eu/api/v2/roles/{role_id}/permissions      |
| app.ddog-gov.com  | DELETE https://api.ddog-gov.com/api/v2/roles/{role_id}/permissions      |
| us2.ddog-gov.com  | DELETE https://api.us2.ddog-gov.com/api/v2/roles/{role_id}/permissions  |
| app.datadoghq.com | DELETE https://api.datadoghq.com/api/v2/roles/{role_id}/permissions     |
| us3.datadoghq.com | DELETE https://api.us3.datadoghq.com/api/v2/roles/{role_id}/permissions |
| us5.datadoghq.com | DELETE https://api.us5.datadoghq.com/api/v2/roles/{role_id}/permissions |

## Get all users of a role →{% #get-all-users-of-a-role %}

| Datadog site      | API endpoint                                                   |
| ----------------- | -------------------------------------------------------------- |
| ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/roles/{role_id}/users |
| ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/roles/{role_id}/users |
| app.datadoghq.eu  | GET https://api.datadoghq.eu/api/v2/roles/{role_id}/users      |
| app.ddog-gov.com  | GET https://api.ddog-gov.com/api/v2/roles/{role_id}/users      |
| us2.ddog-gov.com  | GET https://api.us2.ddog-gov.com/api/v2/roles/{role_id}/users  |
| app.datadoghq.com | GET https://api.datadoghq.com/api/v2/roles/{role_id}/users     |
| us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/roles/{role_id}/users |
| us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/roles/{role_id}/users |

## Add a user to a role →{% #add-a-user-to-a-role %}

| Datadog site      | API endpoint                                                    |
| ----------------- | --------------------------------------------------------------- |
| ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/roles/{role_id}/users |
| ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/roles/{role_id}/users |
| app.datadoghq.eu  | POST https://api.datadoghq.eu/api/v2/roles/{role_id}/users      |
| app.ddog-gov.com  | POST https://api.ddog-gov.com/api/v2/roles/{role_id}/users      |
| us2.ddog-gov.com  | POST https://api.us2.ddog-gov.com/api/v2/roles/{role_id}/users  |
| app.datadoghq.com | POST https://api.datadoghq.com/api/v2/roles/{role_id}/users     |
| us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/roles/{role_id}/users |
| us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/roles/{role_id}/users |

## Remove a user from a role →{% #remove-a-user-from-a-role %}

| Datadog site      | API endpoint                                                      |
| ----------------- | ----------------------------------------------------------------- |
| ap1.datadoghq.com | DELETE https://api.ap1.datadoghq.com/api/v2/roles/{role_id}/users |
| ap2.datadoghq.com | DELETE https://api.ap2.datadoghq.com/api/v2/roles/{role_id}/users |
| app.datadoghq.eu  | DELETE https://api.datadoghq.eu/api/v2/roles/{role_id}/users      |
| app.ddog-gov.com  | DELETE https://api.ddog-gov.com/api/v2/roles/{role_id}/users      |
| us2.ddog-gov.com  | DELETE https://api.us2.ddog-gov.com/api/v2/roles/{role_id}/users  |
| app.datadoghq.com | DELETE https://api.datadoghq.com/api/v2/roles/{role_id}/users     |
| us3.datadoghq.com | DELETE https://api.us3.datadoghq.com/api/v2/roles/{role_id}/users |
| us5.datadoghq.com | DELETE https://api.us5.datadoghq.com/api/v2/roles/{role_id}/users |

## Create a new role by cloning an existing role →{% #create-a-new-role-by-cloning-an-existing-role %}

| Datadog site      | API endpoint                                                    |
| ----------------- | --------------------------------------------------------------- |
| ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/roles/{role_id}/clone |
| ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/roles/{role_id}/clone |
| app.datadoghq.eu  | POST https://api.datadoghq.eu/api/v2/roles/{role_id}/clone      |
| app.ddog-gov.com  | POST https://api.ddog-gov.com/api/v2/roles/{role_id}/clone      |
| us2.ddog-gov.com  | POST https://api.us2.ddog-gov.com/api/v2/roles/{role_id}/clone  |
| app.datadoghq.com | POST https://api.datadoghq.com/api/v2/roles/{role_id}/clone     |
| us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/roles/{role_id}/clone |
| us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/roles/{role_id}/clone |

## List role templates → preview{% #list-role-templates %}

| Datadog site      | API endpoint                                             |
| ----------------- | -------------------------------------------------------- |
| ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/roles/templates |
| ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/roles/templates |
| app.datadoghq.eu  | GET https://api.datadoghq.eu/api/v2/roles/templates      |
| app.ddog-gov.com  | GET https://api.ddog-gov.com/api/v2/roles/templates      |
| us2.ddog-gov.com  | GET https://api.us2.ddog-gov.com/api/v2/roles/templates  |
| app.datadoghq.com | GET https://api.datadoghq.com/api/v2/roles/templates     |
| us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/roles/templates |
| us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/roles/templates |