Create user-managed service accounts | Elasticsearch API documentation

Create user-managed service accounts Generally available; Added in 9.6.0

PUT /_security/service/{namespace}/{service}

Create a service account in a namespace of your own, or replace one that already exists. A replacement is not a partial update: every write applies the defaults, so an account that was disabled and is then written again without enabled comes back enabled.

Creating an account whose name still has leftover service tokens is rejected. Delete those tokens first.

NOTE: The elastic namespace is reserved for the built-in service accounts that ship with Elasticsearch. The manage_service_account privilege does not authorize this API.

Required authorization

Cluster privileges: manage_security

More about service accounts

Path parameters

namespace string Required

The namespace, which is a top-level grouping of service accounts. It must start with a letter or digit and can contain only letters, digits, hyphens, and underscores, up to a maximum of 128 characters. It cannot be elastic, which is reserved for built-in service accounts.
service string Required

The service name. It must start with a letter or digit and can contain only letters, digits, hyphens, and underscores, up to a maximum of 128 characters.

Query parameters

refresh string

If wait_for (the default) then wait for a refresh to make this operation visible to search, if true then refresh the affected shards to make this operation visible to search, if false then do nothing with refreshes.

Default value is wait_for.

application/json

Body Required

roles array[string] Required

The names of the roles to grant to the service account, up to a maximum of 1000. The roles are resolved when the account authenticates, so they do not have to exist yet.
enabled boolean

Whether the account can authenticate. Tokens can still be created for a disabled account; they just cannot be used until the account is enabled.

Default value is true.
description string

A free-text description of the account, as sent on the last PUT of the account. It has no meaning to Elasticsearch. Absent when the account has no description.

Responses

200 application/json
Hide response attribute Show response attribute object
- created boolean Required
  
  A successful call returns a JSON structure that shows whether the service account has been created or updated. When an existing service account is replaced, created is set to false.

PUT /_security/service/{namespace}/{service}

PUT /_security/service/my-namespace/my-service
{
  "roles": [
    "my_role"
  ],
  "enabled": true
}

resp = client.security.put_user_managed_service_account(
    namespace="my-namespace",
    service="my-service",
    roles=[
        "my_role"
    ],
    enabled=True,
)

const response = await client.security.putUserManagedServiceAccount({
  namespace: "my-namespace",
  service: "my-service",
  roles: ["my_role"],
  enabled: true,
});

response = client.security.put_user_managed_service_account(
  namespace: "my-namespace",
  service: "my-service",
  body: {
    "roles": [
      "my_role"
    ],
    "enabled": true
  }
)

$resp = $client->security()->putUserManagedServiceAccount([
    "namespace" => "my-namespace",
    "service" => "my-service",
    "body" => [
        "roles" => array(
            "my_role",
        ),
        "enabled" => true,
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"roles":["my_role"],"enabled":true}' "$ELASTICSEARCH_URL/_security/service/my-namespace/my-service"

Request example

Run `PUT /_security/service/my-namespace/my-service` to create a service account that is granted the `my_role` role and can authenticate.

{
  "roles": [
    "my_role"
  ],
  "enabled": true
}

Response examples (200)

A successful response from `PUT /_security/service/my-namespace/my-service`.

{
  "created": true
}