---
title: OAuth2 in Datadog
description: Learn about how Datadog uses OAuth 2.0.
breadcrumbs: Docs > Extend Datadog > Authorization > OAuth2 in Datadog
---

# OAuth2 in Datadog

## Overview{% #overview %}

This page provides a step-by-step overview on how to implement the OAuth protocol end-to-end on your application once your **confidential** client is created.

{% image
   source="https://datadog-docs.imgix.net/images/extend/authorization/oauth_process.9d9db6156f1955097f5f9981343e79f0.png?auto=format"
   alt="A diagram explaining how the OAuth authentication process works after a user clicks the Connect Account button in an integration tile." /%}

## Implement the OAuth protocol{% #implement-the-oauth-protocol %}

1. Within your Datadog Partner Sandbox Account, create and configure your OAuth client in the [Developer Platform](https://app.datadoghq.com/apps).

1. After a user installs your integration, they can click the **Connect Accounts** button to connect their account in the **Configure** tab of the integration tile.

   {% image
      source="https://datadog-docs.imgix.net/images/extend/authorization/connect-accounts.b7e6551933edd98c0069e9cd9f6e4348.png?auto=format"
      alt="Click the Connect Accounts button" /%}

When a user clicks this button, they are directed to the `onboarding_url` that you provided as a part of the OAuth client creation process. This page should be the sign-in page for your platform.

1. Once a user signs in, redirect them to the [OAuth2 Authorization endpoint](https://docs.datadoghq.com/extend/authorization/oauth2_endpoints/?tab=authorizationendpoints#request-authorization-from-a-user) with the appropriate URL parameters, which includes the added `code_challenge` parameter generated by your application.

To learn how to derive the `code_challenge` parameter, see the PKCE section. Your application must save `code_verifier` for the token request in Step 5.

   - To build the URL for this GET request, use the `site` query parameter that is provided on the redirect to your `onboarding_url`.
   - This parameter is only provided if the user initiates authorization from the Datadog integration tile. See the Initiate authorization from a third-party location section for more options if the user chooses to initiate authorization externally.
   - The `site` query parameter provides the [Datadog site](https://docs.datadoghq.com/getting_started/site/) that the authorizing user is in, as well as any subdomain they may be using, and is required to construct the URL for this GET request to the Authorize endpoint: `<site>/oauth2/v1/authorize?...`.

1. Once a user clicks **Authorize**, Datadog makes a POST request to the authorize endpoint. The user is redirected to the `redirect_uri` that you provided when setting up the OAuth Client with the authorization `code` parameter in the query component.

1. From the `redirect_uri`, make a POST request to the [Datadog token endpoint](https://docs.datadoghq.com/extend/authorization/oauth2_endpoints/?tab=tokenendpoints#exchange-authorization-code-for-access-token) that includes the authorization code from Step 4, the `code_verifier` from Step 3, your OAuth client ID, and client secret.

   - To build the URL for this post request, use the `domain` query parameter that is provided on the redirect to your `redirect_uri`.
   - It is required to construct the URL for this POST request to the token endpoint: `https://api.<domain>/oauth2/v1/token`.

1. Upon success, you receive your `access_token` and `refresh_token` in the response body. Your application should display a confirmation page with the following message: `You may now close this tab`.

1. Use the `access_token` to make calls to Datadog API endpoints by sending it in as a part of the authorization header of your request: `headers = {"Authorization": "Bearer {}".format(access_token)}`.

   - **Note**\*: API endpoints are different in each Datadog site. For example, if a user is in the EU region, the Events endpoint is `https://api.datadoghq.eu/api/v1/events`, while for users in US1, the Events endpoint is `https://api.datadoghq.com/api/v1/events`.
   - Use the `domain` query parameter directly in these API calls to ensure the correct endpoint is being contacted. For example, to make a call to the Events endpoint, you would build your request URL as `https://api.<domain>/api/v1/events`.
   - Some endpoints may also require an API key, which is created in Step 8.

1. Call the [API Key Creation endpoint](https://docs.datadoghq.com/extend/authorization/oauth2_endpoints/?tab=apikeycreationendpoints#create-an-api-key-on-behalf-of-a-user) to generate an API key that allows you to send data on behalf of Datadog users.

If the `API_KEYS_WRITE` scope has not been added to your client, this step fails. This endpoint generates an API Key that is only shown once, and cannot be re-generated unless the user deletes it within their Datadog account. **Store this value in a secure database or location**.

For more information about OAuth client creation, testing and publishing, see [Create an API-based integration](https://docs.datadoghq.com/extend/integrations/api_integration).

### Initiate authorization from a third-party location{% #initiate-authorization-from-a-third-party-location %}

Users can start the authorization process in Datadog by clicking **Connect Accounts** in the integration tile. When a user clicks Connect Accounts in Datadog, information regarding their [Datadog site](https://docs.datadoghq.com/getting_started/site/) is sent on redirect to the `onboarding_url` and on redirect to the `redirect_uri`. The user's Datadog site is required to make API calls on behalf of the user and receive an authorization code. If a user initiates authorization from the *integration's external website*, the user's site information is not provided.

Additionally, when users initiate authorization from the Datadog integration tile, they are required to have corresponding permissions for all requested scopes. If authorization is initiated from somewhere other than the integration tile, users without all of the required permissions may complete authorization (but are prompted to re-authorize with proper permissions when they return to the Datadog integration tile).

Datadog recommends that partners prompt users to initiate authorization from Datadog, rather than from their own platform.

While Datadog does not recommend supporting initiating authorization from a third-party location anywhere outside of the Datadog integration tile, if you do choose to go down this path then you must ensure that you are able to support users in all Datadog sites, and are willing to continue to support new Datadog sites as they may be created. This usually includes implementing a way for the user to manually input their site onto your platform while authorizing.

Keep in mind that organizations may have subdomains as well (for example, [https://subdomain.datadoghq.com](https://subdomain.datadoghq.com)). Subdomains should not be included in API calls, which is why using the `domain` query parameter that's returned on redirect to the `redirect_uri` is recommended when building out the URL for any API call. To ensure that users are authorizing in the correct site, always direct them to the US1 Datadog site (`app.datadoghq.com`), and from there, they can select their region.

## Authorization code grant flow with PKCE{% #authorization-code-grant-flow-with-pkce %}

While the OAuth2 protocol supports several grant flows, the [authorization code grant flow](https://tools.ietf.org/html/rfc6749#section-4.1) with PKCE is the recommended grant type for long-running applications where a user grants explicit consent once and client credentials can be securely stored.

This grant type allows applications to securely obtain a unique authorization code and exchange it for an access token that enables them to make requests to Datadog APIs. The authorization code grant flow consists of three steps:

1. The application [requests authorization from a user](https://docs.datadoghq.com/extend/authorization/oauth2_endpoints/?tab=authorizationendpoints#request-authorization-from-a-user) to access a set of Datadog scopes.
1. When a user clicks **Authorize**, the application [obtains a unique authorization code](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1).
1. The application [exchanges the authorization code for an access token](https://docs.datadoghq.com/extend/authorization/oauth2_endpoints/?tab=tokenendpoints#exchange-authorization-code-for-access-token), which is used to access Datadog APIs.

### Use the PKCE extension{% #use-the-pkce-extension %}

[Proof key for code exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636) is an extension of the OAuth2 authorization code grant flow to protect OAuth2 clients from interception attacks. If an attacker intercepts the flow and gains access to the authorization code before it is returned to the application, they can obtain access tokens and gain access to Datadog APIs.

To mitigate such attacks, the PKCE extension includes the following parameters to securely correlate an authorization request with a token request throughout the grant flow:

| Parameter             | Definition                                                                                                                                                       |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Code Verifier         | A dynamically-generated cryptographic random string.                                                                                                             |
| Code Challenge        | A transformation of the code verifier. The `code_challenge` must use a `base64url` encoding.                                                                     |
| Code Challenge Method | The method used to derive the `code_challenge` from the `code_verifier`. You must use [SHA-256](https://app.datadoghq.com/apps) to compute the `code_challenge`. |

The [PKCE protocol](https://datatracker.ietf.org/doc/html/rfc7636) integrates with the authorization code grant flow by completing the following actions:

- The application generates a `code_verifier` random string and derives the corresponding `code_challenge` using the `code_challenge_method`.

- The application sends an authorization request to Datadog with the `code_challenge` and `code_challenge_method` parameters to obtain an authorization code.

- The application sends a token request to Datadog with the authorization code and `code_verifier` to obtain an access token. The token endpoint verifies the authorization code by transforming the `code_verifier` using the `code_challenge_method` and comparing it with the original `code_challenge` value.

## Further Reading{% #further-reading %}

- [Learn how to use the OAuth 2.0 authorization endpoints](https://docs.datadoghq.com/extend/authorization/oauth2_endpoints)