Request authorization from a user

GET /oauth2/v1/authorize

Overview

To start the authorization code grant flow, an application makes a GET request to Datadog’s authorization endpoint. This redirects a user to Datadog’s authorization-grant flow and renders a consent page displaying the list of scopes requested by your application and a prompt for the user to authorize access. This also returns the Datadog site that the request is being made from.

Request

In the authorization request, the application constructs the redirect URI by adding the following parameters to the query component of the URI using the application/x-www-form-urlencoded format:

Example Request

To render Datadog’s consent page, redirect users to the endpoint with the specified parameters:

https://app.datadoghq.com/oauth2/v1/authorize?redirect_uri=http://localhost:500/oauth_redirect&client_id=abcdefghijklmnopqrstuvwxyz_123456789&response_type=code&code_challenge=12345&code_challenge_method=S256

Success Response

If a user successfully grants the access request, your application obtains an authorization code and redirects the user to the redirect URI with the authorization code, as well as the domain parameter, in the query component.

Error Response

If the request fails due to an invalid redirect_uri or client_id, the user is not redirected to the specified URI; instead, a Datadog error page displays.

If a user denies authorization, or the request fails due to other reasons, the user is redirected to the redirect_uri with an error parameter in the query component.

Obtain an authorization code

POST /oauth2/v1/authorize

Overview

When a user clicks the Authorize button on the consent page, a POST request is automatically sent to the authorization endpoint to verify the request and return a unique authorization code. The user is redirected to your application’s redirect_uri with the authorization code parameter in the query component.

Request

Your application does not need to make this authorization request. This step is a response to the previous user authorization request and is automatically requested by Datadog when a user successfully authorizes an application.

Exchange authorization code for access token

POST /oauth2/v1/token

Overview

Once an authorization code is returned from the authorization request, your application can exchange this code for an access token and a refresh token. The authorization code is extracted from the redirect URI and sent in a POST request to Datadog’s OAuth2 token endpoint.

Datadog access tokens are short-lived tokens with a time-to-live (TTL) of 1 hour that grant access to Datadog APIs. Refresh tokens for Marketplace OAuth clients are long-lived tokens with no expiration (TTL of infinity) that are used to automatically obtain a new access token each time it expires. When a user revokes their authorization, they have to re-authorize a new set of access and refresh tokens for the application (the refresh token expires).

Request

The access token request is made with the following parameters in the body of the POST request with the application/x-www-form-urlencoded format:

Example Request

Use this cURL command to make an access token request:

curl -X POST \
    -d "grant_type=authorization_code&client_id=$CLIENT_ID
    client_secret=$CLIENT_SECRET&redirect_uri=$REDIRECT_URI
    code_verifier=$CODE_VERIFIER&code=$CODE" \
    "https://api.datadoghq.com/oauth2/v1/token"

Success Response

If the access token request is valid and authorized, the token response returns a 200 OK status code with the access token and refresh token contained in the body of the HTTP response.

Error Response

Failed requests made to token endpoints should be handled by the application, such as redirecting users to an appropriate error page on the application.

If a confidential client with an issued client secret makes a token request without providing the client_secret parameter, a 401 Unauthorized status code is returned.

If a token request fails for other reasons, such as a malformed request or an invalid authorization code, a 400 Bad Request status code (unless specified otherwise) is returned with an error parameter.

Revoke tokens

POST /oauth2/v1/revoke

Overview

Users can revoke access or refresh tokens at any time. When revoked, tokens can no longer be used to access Datadog APIs. To revoke a given token, your application makes a POST request to Datadog’s token revocation endpoint.

Request

The revocation request is made with the following parameters in the body of the HTTP POST request with the application/x-www-form-urlencoded format:

Code Example

Use this cURL command to make a revocation request:

curl -X POST \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d 'client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&token=$TOKEN_TO_REVOKE' \
    "https://api.datadoghq.com/oauth2/v1/revoke" \ 

Success Response

If a token has been revoked successfully, or if the token parameter is invalid, the revocation response returns an 200 OK status code.

Error Response

If a token request fails for any reason, such as missing or invalid parameters, 400 Bad Request status code (unless specified otherwise) is returned with an error parameter.

Create an API Key on behalf of a user

POST /api/v2/api_keys/marketplace

Overview

Once you’ve received a valid OAuth access or refresh token, you can use it to create an API key on behalf of the authorizing user.

An API key, created through this endpoint, is the only way to send data into Datadog through OAuth. Only one API key can exist per Datadog organization, and the API Key value is shown once after creation, so store it accordingly.

In order to access this endpoint, the private API_KEYS_WRITE scope must be associated with your OAuth client.

Example Request

Use this cURL command to make a request to the api_keys endpoint:

curl -X POST \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    "https://api.datadoghq.com/api/v2/api_keys/marketplace"

Success Response

If the access or refresh token request is valid and authorized, the following is returned:

{
  "data": {
    "type": "api_keys",
    "attributes": {
      "created_at": "2021-05-06T16:32:07.411970+00:00",
      "key": "ffffffffffffffffffffffffffffffff",
      "last4": "ffff",
      "modified_at": "2021-05-06T16:32:07.411970+00:00",
      "name": "Marketplace Key for App foobar"
    },
    "relationships": {
      "created_by": {
        "data": {
          "type": "users",
          "id": "abcdefgh-abcd-abcd-abcd-abcdefghijkl"
        }
      },
      "modified_by": {
        "data": {
          "type": "users",
          "id": "abcdefgh-abcd-abcd-abcd-abcdefghijkl"
        }
      }
    },
    "id": "abcdefgh-abcd-abcd-abcd-abcdefghijkl01234"
  }
}