---
title: Cloud-based Authentication
description: >-
  Authenticate the Datadog Terraform provider and Datadog Agent using cloud
  credentials instead of static API keys with AWS STS authentication and
  identity mapping.
breadcrumbs: Docs > Account Management > Cloud-based Authentication
---

# Cloud-based Authentication

{% callout %}
##### Join the Preview!

Cloud-based authentication is in Preview. Complete the form to request access.

[Request Access](https://www.datadoghq.com/product-preview/cloud-provider-based-authentication/)
{% /callout %}

## Overview{% #overview %}

Cloud-based authentication lets you authenticate the Datadog Terraform provider and the Datadog Agent using cloud credentials instead of static API and application keys.

During the preview period, AWS is the only supported cloud provider.

Cloud-based authentication is available for the following:

- **Terraform provider**: Authenticate Terraform operations using AWS credentials mapped to a Datadog user or service account
- **Datadog Agent**: Authenticate the Agent using AWS credentials to receive automatically managed and rotated API keys

## How it works: AWS authentication process{% #how-it-works-aws-authentication-process %}

The authentication process uses the [AWS Security Token Service (STS)](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html) to verify your identity.

### Terraform provider authentication flow{% #terraform-provider-authentication-flow %}

1. **Proof generation:** The Datadog Terraform provider creates a signed AWS STS `GetCallerIdentity` request using your current AWS credentials
1. **Proof validation:** Datadog validates the proof by calling AWS STS, which returns your AWS ARN, user ID, and account ID
1. **Identity mapping:** Your AWS identity is mapped to a Datadog service account or user account based on your organization's configuration
1. **Token issue:** If validation succeeds, Datadog issues a temporary JWT token for API access
1. **API authentication:** The token is used for subsequent Datadog API calls

{% alert level="info" %}
If possible, map ARNs to a Datadog service account rather than a user account. Using a service account avoids associating your authentication process with a specific person.
{% /alert %}

### Agent authentication flow{% #agent-authentication-flow %}

1. **Credential detection:** The Agent retrieves AWS credentials from the environment it runs in
1. **Proof generation:** The Agent creates a signed AWS STS request to prove access to the credentials
1. **Proof validation:** Datadog validates the signed request against AWS and verifies it against your organization's intake mapping configuration
1. **API key issue:** If validation succeeds, Datadog issues a managed API key that is automatically rotated
1. **Agent configuration:** The Agent uses the issued API key for all subsequent Datadog API calls

{% alert level="info" %}
If the delegated authentication flow fails, the Agent falls back to the API key configured in your `datadog.yaml` file. This fallback behavior allows you to onboard with limited risk to your existing configuration.
{% /alert %}

## Set up cloud-based authentication for AWS{% #set-up-cloud-based-authentication-for-aws %}

**Requirements**:

- Datadog Terraform provider version 3.70 or later.
- You have configured the [Datadog-AWS integration](https://app.datadoghq.com/integrations/amazon-web-services) and added your AWS account. See the [AWS Integration docs](https://docs.datadoghq.com/integrations/amazon-web-services/).
- Your account has the `cloud_auth_config_read` and `cloud_auth_config_write` permissions. These permissions are available only after you are onboarded to the preview.

Setting up cloud-provider based authentication for AWS involves two parts:

1. Configuring your AWS identity mapping in Datadog
1. Updating your Terraform provider configuration

### Configure AWS identity mapping in Datadog{% #configure-aws-identity-mapping-in-datadog %}

{% alert level="info" %}
For identity mapping to work, your AWS account **must be integrated** with Datadog through the [Datadog-AWS integration](https://app.datadoghq.com/integrations/amazon-web-services). If an AWS account is not integrated, the authentication flow cannot verify the caller, and mapping fails.
{% /alert %}

First, map your AWS identities (ARNs) to Datadog service accounts or user accounts. During the preview, you must perform the mapping using the Datadog API.

If you need to create IAM roles in AWS, see the [AWS IAM role creation documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html).

#### Map an AWS ARN to a Datadog user account{% #map-an-aws-arn-to-a-datadog-user-account %}

For `account_identifier`, use the email shown in the user's Datadog profile.

**Example**: An API call that maps an AWS ARN to a Datadog user account, `john.doe@myorg.com`.

```bash
# Example: map an AWS ARN to a Datadog User
curl -X POST "/api/v2/cloud_auth/aws/persona_mapping" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d '{
  "data": {
    "type": "aws_cloud_auth_config",
    "attributes": {
      "account_identifier": "john.doe@myorg.com",
      "arn_pattern": "arn:aws:sts::123456789012:assumed-role/terraform-runner"
    }
  }
}'
```

#### Map an AWS ARN to a Datadog service account{% #map-an-aws-arn-to-a-datadog-service-account %}

For `account_identifier`, you can use either:

- The service account's **UUID**: Go to **Organization settings > Service accounts**, click the service account you want to map, and copy the `service_account_id` from the URL. For example, if the URL ends in `/organization-settings/service-accounts?service_account_id=3fa85f64-5717-4562-b3fc-2c963f66afa6`, then use `3fa85f64-5717-4562-b3fc-2c963f66afa6`.
- The service account's **email address**: Use the email address shown in the service account's details.

**Example**: An API call that maps an AWS ARN to a Datadog service account using the UUID, `3fa85f64-5717-4562-b3fc-2c963f66afa6`.

```bash
# Example: map an AWS ARN to a Datadog Service Account using UUID
curl -X POST "/api/v2/cloud_auth/aws/persona_mapping" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d '{
  "data": {
    "type": "aws_cloud_auth_config",
    "attributes": {
      "account_identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "arn_pattern": "arn:aws:sts::123456789012:assumed-role/terraform-runner"
    }
  }
}'
```

**Example**: An API call that maps an AWS ARN to a Datadog service account using the email address, `terraform-service-account@myorg.com`.

```bash
# Example: map an AWS ARN to a Datadog Service Account using email
curl -X POST "/api/v2/cloud_auth/aws/persona_mapping" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d '{
  "data": {
    "type": "aws_cloud_auth_config",
    "attributes": {
      "account_identifier": "terraform-service-account@myorg.com",
      "arn_pattern": "arn:aws:sts::123456789012:assumed-role/terraform-runner"
    }
  }
}'
```

#### Using wildcards in ARN patterns{% #using-wildcards-in-arn-patterns %}

ARN patterns support wildcard matching to handle dynamic or variable portions of resource ARNs. This is useful when working with assumed roles that include session identifiers or other variable components.

**Wildcard rules**:

- Wildcards (`*`) are only allowed in the last portion of the resource ARN
- You must specify a specific resource before the wildcard
- Wildcards cannot be placed in the middle of the ARN

**Example**: Match any session assuming the `DatadogTerraformerRole`:

```bash
curl -X POST "/api/v2/cloud_auth/aws/persona_mapping" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d '{
  "data": {
    "type": "aws_cloud_auth_config",
    "attributes": {
      "account_identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "arn_pattern": "arn:aws:sts::123456789012:assumed-role/DatadogTerraformerRole/*"
    }
  }
}'
```

This pattern matches actual assumed role ARNs like:

- `arn:aws:sts::123456789012:assumed-role/DatadogTerraformerRole/run-abcdefghijk`
- `arn:aws:sts::123456789012:assumed-role/DatadogTerraformerRole/session-xyz789`

{% alert level="info" %}
Wildcard matching is particularly useful for CI/CD pipelines where role sessions have dynamically generated identifiers.
{% /alert %}

#### List existing mappings{% #list-existing-mappings %}

```bash
curl -X GET "/api/v2/cloud_auth/aws/persona_mapping" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
```

### Update your Terraform provider configuration{% #update-your-terraform-provider-configuration %}

After you configured the identity mapping, update your Datadog Terraform provider configuration to use cloud provider authentication:

#### Remove your existing configuration{% #remove-your-existing-configuration %}

```hcl
# Old configuration
provider "datadog" {
  api_key = var.datadog_api_key
  app_key = var.datadog_app_key
}
```

#### Add the new cloud authentication configuration{% #add-the-new-cloud-authentication-configuration %}

To get your `org_uuid`, call this endpoint, or click the link (requires an active session in the target org): [/api/v2/current_user](https://app.datadoghq.com/api/v2/current_user)

```hcl
# New configuration using AWS authentication
provider "datadog" {
  org_uuid             = var.datadog_org_uuid
  cloud_provider_type  = "aws"
}
```

#### Optional - Specify AWS credentials explicitly{% #optional---specify-aws-credentials-explicitly %}

As an alternative to using environment variables or AWS credential files, you can specify AWS credentials directly in your Terraform configuration:

```hcl
provider "datadog" {
  org_uuid              = var.datadog_org_uuid
  cloud_provider_type   = "aws"
  aws_access_key_id     = var.aws_access_key_id
  aws_secret_access_key = var.aws_secret_access_key
  aws_session_token     = var.aws_session_token  # If using temporary credentials
}
```

The Terraform provider automatically uses your configured AWS credentials to authenticate with Datadog.

## Set up cloud-based authentication for the Datadog Agent{% #set-up-cloud-based-authentication-for-the-datadog-agent %}

Cloud-based authentication for the Agent allows you to authenticate your Agent using AWS credentials instead of managing static API keys. The Agent exchanges an AWS authentication proof for a managed API key that Datadog automatically rotates.

**Requirements**:

- Version `7.78.0` or later of the Datadog Agent.
- The Agent runs in an AWS environment with access to AWS credentials (for example, an EC2 instance with an IAM role, ECS task, or EKS pod).
- You have configured the [Datadog-AWS integration](https://app.datadoghq.com/integrations/amazon-web-services) and added your AWS account. See the [AWS Integration docs](https://docs.datadoghq.com/integrations/amazon-web-services/).
- Your account has the `cloud_auth_config_read` and `cloud_auth_config_write` permissions. These permissions are available only after you are onboarded to the preview.

Setting up cloud-based authentication for the Agent involves two parts:

1. Configuring your AWS intake mapping in Datadog
1. Updating your Agent configuration

### Configure AWS intake mapping in Datadog{% #configure-aws-intake-mapping-in-datadog %}

{% alert level="info" %}
For intake mapping to work, your AWS account **must be integrated** with Datadog through the [Datadog-AWS integration](https://app.datadoghq.com/integrations/amazon-web-services). If an AWS account is not integrated, the authentication flow cannot verify the caller, and mapping fails.
{% /alert %}

First, configure intake mappings to authorize specific AWS ARN patterns for Agent authentication. Unlike the persona mapping used for Terraform, intake mapping only requires an ARN pattern. No Datadog account identifier is needed, because the Agent authenticates to send data rather than perform user actions.

If you need to create IAM roles in AWS, see the [AWS IAM role creation documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html).

#### Create an intake mapping{% #create-an-intake-mapping %}

**Example**: An API call that authorizes Agents running with a specific IAM role to authenticate.

```bash
curl -X POST "/api/v2/cloud_auth/aws/intake_mapping" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d '{
  "data": {
    "type": "aws_cloud_auth_intake_mapping",
    "attributes": {
      "arn_pattern": "arn:aws:sts::123456789012:assumed-role/DatadogAgentRole/*"
    }
  }
}'
```

#### Using wildcards in ARN patterns{% #using-wildcards-in-arn-patterns-1 %}

ARN patterns support wildcard matching to handle dynamic or variable portions of resource ARNs. This is useful when working with assumed roles that include session identifiers or when you have multiple Agent instances.

**Wildcard rules**:

- Wildcards (`*`) are only allowed in the last portion of the resource ARN
- You must specify a specific resource before the wildcard
- Wildcards cannot be placed in the middle of the ARN

**Example**: Match any session assuming the `DatadogAgentRole`:

```bash
curl -X POST "/api/v2/cloud_auth/aws/intake_mapping" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d '{
  "data": {
    "type": "aws_cloud_auth_intake_mapping",
    "attributes": {
      "arn_pattern": "arn:aws:sts::123456789012:assumed-role/DatadogAgentRole/*"
    }
  }
}'
```

This pattern matches actual assumed role ARNs like:

- `arn:aws:sts::123456789012:assumed-role/DatadogAgentRole/i-0abc123def456`
- `arn:aws:sts::123456789012:assumed-role/DatadogAgentRole/eks-datadog-agent-xyz`

#### List existing intake mappings{% #list-existing-intake-mappings %}

```bash
curl -X GET "/api/v2/cloud_auth/aws/intake_mapping" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
```

#### Delete an intake mapping{% #delete-an-intake-mapping %}

```bash
curl -X DELETE "/api/v2/cloud_auth/aws/intake_mapping/<MAPPING_UUID>" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
```

### Update your Agent configuration{% #update-your-agent-configuration %}

After you configure the intake mapping, update your Agent configuration to use cloud-based authentication.

#### Global configuration{% #global-configuration %}

Add the `delegated_auth` section to your `datadog.yaml` file to enable cloud-based authentication for all Agent data:

```yaml
delegated_auth:
  org_uuid: <YOUR_ORG_UUID>
```

To get your `org_uuid`, call this endpoint, or click the link (requires an active session in the target org): [/api/v2/current_user](https://app.datadoghq.com/api/v2/current_user)

The Agent auto-detects if it runs in an AWS environment and uses the available AWS credentials.

#### Provider-specific options{% #provider-specific-options %}

To explicitly configure AWS as your authentication provider and specify provider-specific options, use the `provider` and `aws` subsections:

```yaml
delegated_auth:
  org_uuid: <YOUR_ORG_UUID>
  provider: aws  # Optional: auto-detects if omitted
  aws:
    region: <AWS_REGION>  # Optional: auto-detects from IMDS if omitted or uses global STS
```

Replace `<AWS_REGION>` with the AWS region to use for STS authentication (for example, `us-east-1`).

#### Per-product configuration{% #per-product-configuration %}

You can enable delegated authentication for specific Agent products independently. This is useful when you want to send different data types to different Datadog organizations, or when you only want to use cloud-based authentication for specific products.

To enable delegated authentication for logs only:

```yaml
logs_config:
  delegated_auth:
    org_uuid: <YOUR_ORG_UUID>
```

To use different organizations for different products:

```yaml
delegated_auth:
  org_uuid: <YOUR_GLOBAL_ORG_UUID>
  provider: aws
  aws:
    region: <AWS_REGION>

logs_config:
  delegated_auth:
    org_uuid: <YOUR_LOGS_ORG_UUID>
```

{% alert level="info" %}
Provider-specific settings (such as `provider` and `aws`) are only configured in the global `delegated_auth` section. Per-product sections only support `org_uuid`.
{% /alert %}

#### Fallback behavior{% #fallback-behavior %}

If the delegated authentication flow fails for any reason, the Agent automatically falls back to using the API key configured in your `datadog.yaml` file. This fallback behavior provides a safety net during onboarding and protects against authentication service disruptions.

To take advantage of this fallback, keep your existing `api_key` configuration alongside the new `delegated_auth` configuration:

```yaml
api_key: <YOUR_API_KEY>

delegated_auth:
  org_uuid: <YOUR_ORG_UUID>
```

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

- [Managing Datadog with Terraform](https://docs.datadoghq.com/getting_started/integrations/terraform/)
- [Agent Configuration](https://docs.datadoghq.com/agent/configuration/)
- [API and Application Keys](https://docs.datadoghq.com/account_management/api-app-keys/)
- [AWS Integration](https://docs.datadoghq.com/integrations/amazon_web_services/)