New announcements for Serverless, Network, RUM, and more from Dash! New announcements from Dash!

Roles API

Ask your sales representative or customer success manager to enable this feature.

The Roles API can be used to create and manage Datadog roles, what global permissions 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 the Datadog application from the Pipelines Page.

Get All Roles

Description: Returns all roles, including their names and uuids.
Method: GET
Endpoint: api/v1/roles
Required Payload: No Payload

ARGUMENTS
  • sort_field [optional, default=name]: Sort roles by the given field. Options: name
  • sort_dir [optional, default=asc]: Direction of sort. Options: asc, desc
  • start [optional, default=0]: Page number
  • count [optional, default=10]: Number of roles to return for a given page

Example:

curl -X GET "https://app.datadoghq.com/api/v1/roles?api_key=${API_KEY}&application_key=${APP_KEY}"

# Response:
# [{
#   "id": <number>,
#   "name": <string>,
#   "uuid": <string>
#  }, ...]

Get One Role

Description: Returns a specific role, including its name and uuid.
Method: GET
Endpoint: api/v1/roles/$ROLE_UUID
Required Payload: No Payload
Example:

curl -X GET "https://app.datadoghq.com/api/v1/roles/${ROLEUUID}?api_key=${API_KEY}&application_key=${APP_KEY}"

# Response:
# {
#  "id": <number>,
#  "name": <string>,
#  "uuid": <string>
# }

Create Role

Description: Creates a new role. Returns role name and uuid.
Method: POST
Endpoint: api/v1/roles
Required Payload: “name”
Example:

curl -X POST -H "Content-type: application/json" -d "{\"name\":\"${ROLENAME}\"}" "https://app.datadoghq.com/api/v1/roles?api_key=${API_KEY}&application_key=${APP_KEY}"

Update Role

Description: Updates an existing role’s name. Returns role name and uuid.
Method: PUT
Endpoint: api/v1/roles/$ROLE_UUID
Required Payload: “name”
Example:

curl -X PUT -H "Content-type: application/json" -d "{\"name\":\"${ROLENAME}\"}" "https://app.datadoghq.com/api/v1/roles/${ROLEUUID}?api_key=${API_KEY}&application_key=${APP_KEY}"

Delete Role

Description: Deletes a role.
Method: DELETE
Endpoint: api/v1/roles/$ROLE_UUID
Required Payload: No Payload
Example:

curl -X DELETE "https://app.datadoghq.com/api/v1/roles/${ROLEUUID}?api_key=${API_KEY}&application_key=${APP_KEY}"

Get Permissions

Description: Returns a list of all permissions, including name, description, uuid.
Method: GET
Endpoint: api/v1/permissions
Required Payload: No Payload
Example:

curl -X GET "https://app.datadoghq.com/api/v1/permissions?api_key=${API_KEY}&application_key=${APP_KEY}"

# Response:
# [{
#   "created_at": <string>,
#   "description": <string>,
#   "display_name": <string>,
#   "uuid": <string>,
#   "name": <string>
# }, ...]

Grant Permission to Role

Description: Adds a permission to a role.
Method: POST
Endpoint: api/v1/roles/$ROLE_UUID/permissions/$PERMISSION_UUID
Required Payload: Empty ({})
Example:

curl -X POST -H "Content-type: application/json" -d "{}" "https://app.datadoghq.com/api/v1/roles/${ROLEUUID}/permissions/${PERMISSION}?api_key=${API_KEY}&application_key=${APP_KEY}"

Revoke Permission from Role

Description: Removes a permission from a role.
Method: DELETE
Endpoint: api/v1/roles/$ROLE_UUID/permissions/$PERMISSION_UUID
Required Payload: Empty ({})
Example:

curl -X DELETE -H "Content-type: application/json" -d "{}" "https://app.datadoghq.com/api/v1/roles/${ROLEUUID}/permissions/${PERMISSION}?api_key=${API_KEY}&application_key=${APP_KEY}"

Add User to Role

Description: Adds a user to a role.
Method: POST
Endpoint: api/v1/roles/$ROLE_UUID/users/$USER_HANDLE
Required Payload: Empty ({})
Example:

curl -X POST -H "Content-type: application/json" -d "{}" "https://app.datadoghq.com/api/v1/roles/${ROLEUUID}/users/${USER}?api_key=${API_KEY}&application_key=${APP_KEY}"

Remove User from Role

Description: Removes a user from a role.
Method: DELETE
Endpoint: api/v1/roles/$ROLE_UUID/users/$USER_HANDLE
Required Payload: Empty ({})
Example:

curl -X DELETE -H "Content-type: application/json" -d "{}" "https://app.datadoghq.com/api/v1/roles/${ROLEUUID}/users/${USER}?api_key=${API_KEY}&application_key=${APP_KEY}"

Permission UUIDs

In order to grant or remove a global permission to/from a role, today you must know and use the UUID for (A) the role and (B) the permission.

The UUID of the roles can be found from the GET roles api call.

The UUIDs for the permissions are as follows:

nameuuiddescription
admin984a2bd4-d3b4-11e8-a1ff-a7f660d43029Read and write permission to all of datadog
standard984d2f00-d3b4-11e8-a200-bb47109e9987Read and write permission to most of datadog
read_only984fe6fa-d3b4-11e8-a201-47a7999cc331Read permission to most of datadog
logs_read_index_data5e605652-dd12-11e8-9e53-375565b8970eRead a subset of all log indexes
logs_modify_indexes62cc036c-dd12-11e8-9e54-db9995643092Update the definition of log indexes
logs_live_tail6f66600e-dd12-11e8-9e55-7f30fbb45e73Access the live tail feature
logs_write_exclusion_filters7d7c98ac-dd12-11e8-9e56-93700598622dUpdate a subset of the exclusion filters
logs_write_pipelines811ac4ca-dd12-11e8-9e57-676a7f0beef9Update a subset of the log pipelines
logs_write_processors84aa3ae4-dd12-11e8-9e58-a373a514ccd0Update the log processors in an index
logs_write_archives87b00304-dd12-11e8-9e59-cbeb5f71f72fUpdate the external archives configuration
logs_public_config_api1a92ede2-6cb2-11e9-99c6-2b3a4a0cdf0aAccess the Logs Public Config API (r/w)
nameuuiddescription
adminf1624684-d87d-11e8-acac-efb4dbffab1cRead and write permission to all of datadog
standardf1666372-d87d-11e8-acac-6be484ba794aRead and write permission to most of datadog
read_onlyf1682b6c-d87d-11e8-acac-9f3040c65f48Read permission to most of datadog
logs_read_index_data4fbb1652-dd15-11e8-9308-77be61fbb2c7Read a subset of all log indexes
logs_modify_indexes4fbd1e66-dd15-11e8-9308-53cb90e4ef1cUpdate the definition of log indexes
logs_live_tail4fbeec96-dd15-11e8-9308-d3aac44f93e5Access the live tail feature
logs_write_exclusion_filters4fc2807c-dd15-11e8-9308-d3bfffb7f039Update a subset of the exclusion filters
logs_write_pipelines4fc43656-dd15-11e8-9308-f3e2bb5e31b4Update a subset of the log pipelines
logs_write_processors505f4538-dd15-11e8-9308-47a4732f715fUpdate the log processors in an index
logs_write_archives505fd138-dd15-11e8-9308-afd2db62791eUpdate the external archives configuration
logs_public_config_apibd837a80-6cb2-11e9-8fc4-339b4b012214Access the Logs Public Config API (r/w)

Granting Permissions within limited scopes

Certain permissions can be granted within a limited scope. This can be done manually from the Datadog application in the Pipelines Page, or programmatically via the Role API if the correct “scope” is added in the payload. The following permissions can be granted within a limited scope:

Permission NameScope NameFormatDescription
logs_read_index_dataindexeslist of index names (string)Grant read on only certain log indexes.
logs_write_exclusion_filtersindexeslist of index names (string)Grant update on the exclusion filters for only certain indexes.
logs_write_processorspipelineslist of processing pipeline ids (string)Grant update on only the processors of certain pipelines.

For example, to grant read access only on two indexes named main and support to a role named support, your API call would look like this:

curl -X POST -H "Content-type: application/json" -d '{"scope": {"indexes": ["main", "support"]}}' "https://app.datadoghq.com/api/v1/roles/${ROLEUUID}/permissions/${PERMISSION}?api_key=${API_KEY}&application_key=${APP_KEY}"

To grant write access to only two processing pipelines whose IDs are abcd-1234 and bcde-2345 respectively, your API call would look like this:

curl -X POST -H "Content-type: application/json" -d '{"scope": {"pipelines": ["abcd-1234", "bcde-2345"]}}' "https://app.datadoghq.com/api/v1/roles/${ROLEUUID}/permissions/${PERMISSION}?api_key=${API_KEY}&application_key=${APP_KEY}"

Further Reading

Additional helpful documentation, links, and articles: