Create a service account

POST https://api.ap1.datadoghq.com/api/v2/service_accountshttps://api.ap2.datadoghq.com/api/v2/service_accountshttps://api.datadoghq.eu/api/v2/service_accountshttps://api.ddog-gov.com/api/v2/service_accountshttps://api.us2.ddog-gov.com/api/v2/service_accountshttps://api.datadoghq.com/api/v2/service_accountshttps://api.us3.datadoghq.com/api/v2/service_accountshttps://api.us5.datadoghq.com/api/v2/service_accounts

Overview

Create a service account for your organization. This endpoint requires the service_account_write permission.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

Object to create a service account User.

attributes [required]

object

Attributes of the created user.

email [required]

string

The email of the user.

name

string

The name of the user.

service_account [required]

boolean

Whether the user is a service account. Must be true.

title

string

The title of the user.

relationships

object

Relationships of the user object.

roles

object

Relationship to roles.

data

[object]

An array containing type and the unique identifier of a role.

id

string

The unique identifier of the role.

type

enum

Roles type. Allowed enum values: roles

default: roles

type [required]

enum

Users resource type. Allowed enum values: users

default: users

{
  "data": {
    "type": "users",
    "attributes": {
      "name": "Test API Client",
      "email": "Example-Service-Account@datadoghq.com",
      "service_account": true
    },
    "relationships": {
      "roles": {
        "data": [
          {
            "id": "string",
            "type": "roles"
          }
        ]
      }
    }
  }
}

Response

OK

Response containing information about a single user.

Expand All

Field

Type

Description

data

object

User object returned by the API.

attributes

object

Attributes of user object returned by the API.

created_at

date-time

The ISO 8601 timestamp of when the user account was created.

disabled

boolean

Whether the user account is deactivated. Disabled users cannot log in.

email

string

The email address of the user, used for login and notifications.

handle

string

The unique handle (username) of the user, typically matching their email prefix.

icon

string

URL of the user's profile icon, typically a Gravatar URL derived from the email address.

last_login_time

date-time

The ISO 8601 timestamp of the user's most recent login, or null if the user has never logged in.

mfa_enabled

boolean

Whether multi-factor authentication (MFA) is enabled for the user's account.

modified_at

date-time

The ISO 8601 timestamp of when the user account was last modified.

name

string

The full display name of the user as shown in the Datadog UI.

service_account

boolean

Whether this is a service account rather than a human user. Service accounts are used for programmatic API access.

status

string

The current status of the user account (for example, Active, Pending, or Disabled).

title

string

The job title of the user (for example, "Senior Engineer" or "Product Manager").

uuid

string

The globally unique identifier (UUID) of the user.

verified

boolean

Whether the user's email address has been verified.

id

string

ID of the user.

relationships

object

Relationships of the user object returned by the API.

org

object

Relationship to an organization.

data [required]

object

Relationship to organization object.

id [required]

string

ID of the organization.

type [required]

enum

Organizations resource type. Allowed enum values: orgs

default: orgs

other_orgs

object

Relationship to organizations.

data [required]

[object]

Relationships to organization objects.

id [required]

string

ID of the organization.

type [required]

enum

Organizations resource type. Allowed enum values: orgs

default: orgs

other_users

object

Relationship to users.

data [required]

[object]

Relationships to user objects.

id [required]

string

A unique identifier that represents the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

roles

object

Relationship to roles.

data

[object]

An array containing type and the unique identifier of a role.

id

string

The unique identifier of the role.

type

enum

Roles type. Allowed enum values: roles

default: roles

type

enum

Users resource type. Allowed enum values: users

default: users

included

[ <oneOf>]

Array of objects related to the user.

Option 1

object

Organization object.

attributes

object

Attributes of the organization.

created_at

date-time

Creation time of the organization.

description

string

Description of the organization.

disabled

boolean

Whether or not the organization is disabled.

modified_at

date-time

Time of last organization modification.

name

string

Name of the organization.

public_id

string

Public ID of the organization.

sharing

string

Sharing type of the organization.

url

string

URL of the site that this organization exists at.

id

string

ID of the organization.

type [required]

enum

Organizations resource type. Allowed enum values: orgs

default: orgs

Option 2

object

Permission object.

attributes

object

Attributes of a permission.

created

date-time

Creation time of the permission.

description

string

Description of the permission.

display_name

string

Displayed name for the permission.

display_type

string

Display type.

group_name

string

Name of the permission group.

name

string

Name of the permission.

name_aliases

[string]

List of alias names for the permission.

restricted

boolean

Whether or not the permission is restricted.

id

string

ID of the permission.

type [required]

enum

Permissions resource type. Allowed enum values: permissions

default: permissions

Option 3

object

Role object returned by the API.

attributes

object

Attributes of the role.

created_at

date-time

Creation time of the role.

modified_at

date-time

Time of last role modification.

name

string

The name of the role. The name is neither unique nor a stable identifier of the role.

receives_permissions_from

[string]

The managed role from which this role automatically inherits new permissions. Specify one of the following: "Datadog Admin Role", "Datadog Standard Role", or "Datadog Read Only Role". If empty or not specified, the role does not automatically inherit permissions from any managed role.

user_count

int64

Number of users with that role.

id

string

The unique identifier of the role.

relationships

object

Relationships of the role object returned by the API.

permissions

object

Relationship to multiple permissions objects.

data

[object]

Relationships to permission objects.

id

string

ID of the permission.

type

enum

Permissions resource type. Allowed enum values: permissions

default: permissions

type [required]

enum

Roles type. Allowed enum values: roles

default: roles

{
  "data": {
    "attributes": {
      "created_at": "2019-09-19T10:00:00.000Z",
      "disabled": false,
      "email": "string",
      "handle": "string",
      "icon": "string",
      "last_login_time": "2019-09-19T10:00:00.000Z",
      "mfa_enabled": false,
      "modified_at": "2019-09-19T10:00:00.000Z",
      "name": "string",
      "service_account": false,
      "status": "string",
      "title": "string",
      "uuid": "string",
      "verified": false
    },
    "id": "string",
    "relationships": {
      "org": {
        "data": {
          "id": "00000000-0000-beef-0000-000000000000",
          "type": "orgs"
        }
      },
      "other_orgs": {
        "data": [
          {
            "id": "00000000-0000-beef-0000-000000000000",
            "type": "orgs"
          }
        ]
      },
      "other_users": {
        "data": [
          {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "users"
          }
        ]
      },
      "roles": {
        "data": [
          {
            "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d",
            "type": "roles"
          }
        ]
      }
    },
    "type": "users"
  },
  "included": [
    {
      "attributes": {
        "created_at": "2019-09-19T10:00:00.000Z",
        "description": "string",
        "disabled": false,
        "modified_at": "2019-09-19T10:00:00.000Z",
        "name": "string",
        "public_id": "string",
        "sharing": "string",
        "url": "string"
      },
      "id": "string",
      "type": "orgs"
    }
  ]
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Authentication error

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                          ## default
# 

# Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/service_accounts" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "email": "jane.doe@example.com", "service_account": true }, "relationships": { "roles": { "data": [ { "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d" } ] } }, "type": "users" } } EOF
// Create a service account returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	// there is a valid "role" in the system
	RoleDataID := os.Getenv("ROLE_DATA_ID")

	body := datadogV2.ServiceAccountCreateRequest{
		Data: datadogV2.ServiceAccountCreateData{
			Type: datadogV2.USERSTYPE_USERS,
			Attributes: datadogV2.ServiceAccountCreateAttributes{
				Name:           datadog.PtrString("Test API Client"),
				Email:          "Example-Service-Account@datadoghq.com",
				ServiceAccount: true,
			},
			Relationships: &datadogV2.UserRelationships{
				Roles: &datadogV2.RelationshipToRoles{
					Data: []datadogV2.RelationshipToRoleData{
						{
							Id:   datadog.PtrString(RoleDataID),
							Type: datadogV2.ROLESTYPE_ROLES.Ptr(),
						},
					},
				},
			},
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewServiceAccountsApi(apiClient)
	resp, r, err := api.CreateServiceAccount(ctx, body)

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `ServiceAccountsApi.CreateServiceAccount`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `ServiceAccountsApi.CreateServiceAccount`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" go run "main.go"
// Create a service account returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.ServiceAccountsApi;
import com.datadog.api.client.v2.model.RelationshipToRoleData;
import com.datadog.api.client.v2.model.RelationshipToRoles;
import com.datadog.api.client.v2.model.RolesType;
import com.datadog.api.client.v2.model.ServiceAccountCreateAttributes;
import com.datadog.api.client.v2.model.ServiceAccountCreateData;
import com.datadog.api.client.v2.model.ServiceAccountCreateRequest;
import com.datadog.api.client.v2.model.UserRelationships;
import com.datadog.api.client.v2.model.UserResponse;
import com.datadog.api.client.v2.model.UsersType;
import java.util.Collections;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    ServiceAccountsApi apiInstance = new ServiceAccountsApi(defaultClient);

    // there is a valid "role" in the system
    String ROLE_DATA_ID = System.getenv("ROLE_DATA_ID");

    ServiceAccountCreateRequest body =
        new ServiceAccountCreateRequest()
            .data(
                new ServiceAccountCreateData()
                    .type(UsersType.USERS)
                    .attributes(
                        new ServiceAccountCreateAttributes()
                            .name("Test API Client")
                            .email("Example-Service-Account@datadoghq.com")
                            .serviceAccount(true))
                    .relationships(
                        new UserRelationships()
                            .roles(
                                new RelationshipToRoles()
                                    .data(
                                        Collections.singletonList(
                                            new RelationshipToRoleData()
                                                .id(ROLE_DATA_ID)
                                                .type(RolesType.ROLES))))));

    try {
      UserResponse result = apiInstance.createServiceAccount(body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling ServiceAccountsApi#createServiceAccount");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" java "Example.java"
"""
Create a service account returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.service_accounts_api import ServiceAccountsApi
from datadog_api_client.v2.model.relationship_to_role_data import RelationshipToRoleData
from datadog_api_client.v2.model.relationship_to_roles import RelationshipToRoles
from datadog_api_client.v2.model.roles_type import RolesType
from datadog_api_client.v2.model.service_account_create_attributes import ServiceAccountCreateAttributes
from datadog_api_client.v2.model.service_account_create_data import ServiceAccountCreateData
from datadog_api_client.v2.model.service_account_create_request import ServiceAccountCreateRequest
from datadog_api_client.v2.model.user_relationships import UserRelationships
from datadog_api_client.v2.model.users_type import UsersType

# there is a valid "role" in the system
ROLE_DATA_ID = environ["ROLE_DATA_ID"]

body = ServiceAccountCreateRequest(
    data=ServiceAccountCreateData(
        type=UsersType.USERS,
        attributes=ServiceAccountCreateAttributes(
            name="Test API Client",
            email="Example-Service-Account@datadoghq.com",
            service_account=True,
        ),
        relationships=UserRelationships(
            roles=RelationshipToRoles(
                data=[
                    RelationshipToRoleData(
                        id=ROLE_DATA_ID,
                        type=RolesType.ROLES,
                    ),
                ],
            ),
        ),
    ),
)

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = ServiceAccountsApi(api_client)
    response = api_instance.create_service_account(body=body)

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" python3 "example.py"
# Create a service account returns "OK" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V2::ServiceAccountsAPI.new

# there is a valid "role" in the system
ROLE_DATA_ID = ENV["ROLE_DATA_ID"]

body = DatadogAPIClient::V2::ServiceAccountCreateRequest.new({
  data: DatadogAPIClient::V2::ServiceAccountCreateData.new({
    type: DatadogAPIClient::V2::UsersType::USERS,
    attributes: DatadogAPIClient::V2::ServiceAccountCreateAttributes.new({
      name: "Test API Client",
      email: "Example-Service-Account@datadoghq.com",
      service_account: true,
    }),
    relationships: DatadogAPIClient::V2::UserRelationships.new({
      roles: DatadogAPIClient::V2::RelationshipToRoles.new({
        data: [
          DatadogAPIClient::V2::RelationshipToRoleData.new({
            id: ROLE_DATA_ID,
            type: DatadogAPIClient::V2::RolesType::ROLES,
          }),
        ],
      }),
    }),
  }),
})
p api_instance.create_service_account(body)

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" rb "example.rb"
// Create a service account returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_service_accounts::ServiceAccountsAPI;
use datadog_api_client::datadogV2::model::RelationshipToRoleData;
use datadog_api_client::datadogV2::model::RelationshipToRoles;
use datadog_api_client::datadogV2::model::RolesType;
use datadog_api_client::datadogV2::model::ServiceAccountCreateAttributes;
use datadog_api_client::datadogV2::model::ServiceAccountCreateData;
use datadog_api_client::datadogV2::model::ServiceAccountCreateRequest;
use datadog_api_client::datadogV2::model::UserRelationships;
use datadog_api_client::datadogV2::model::UsersType;

#[tokio::main]
async fn main() {
    // there is a valid "role" in the system
    let role_data_id = std::env::var("ROLE_DATA_ID").unwrap();
    let body =
        ServiceAccountCreateRequest::new(
            ServiceAccountCreateData::new(
                ServiceAccountCreateAttributes::new(
                    "Example-Service-Account@datadoghq.com".to_string(),
                    true,
                )
                .name("Test API Client".to_string()),
                UsersType::USERS,
            )
            .relationships(UserRelationships::new().roles(
                RelationshipToRoles::new().data(vec![RelationshipToRoleData::new()
                    .id(role_data_id.clone())
                    .type_(RolesType::ROLES)]),
            )),
        );
    let configuration = datadog::Configuration::new();
    let api = ServiceAccountsAPI::with_config(configuration);
    let resp = api.create_service_account(body).await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" cargo run
/**
 * Create a service account returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
const apiInstance = new v2.ServiceAccountsApi(configuration);

// there is a valid "role" in the system
const ROLE_DATA_ID = process.env.ROLE_DATA_ID as string;

const params: v2.ServiceAccountsApiCreateServiceAccountRequest = {
  body: {
    data: {
      type: "users",
      attributes: {
        name: "Test API Client",
        email: "Example-Service-Account@datadoghq.com",
        serviceAccount: true,
      },
      relationships: {
        roles: {
          data: [
            {
              id: ROLE_DATA_ID,
              type: "roles",
            },
          ],
        },
      },
    },
  },
};

apiInstance
  .createServiceAccount(params)
  .then((data: v2.UserResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" tsc "example.ts"