---
type: api
title: Create user-managed service accounts
description: Create a service account in a namespace of your own, or replace one that already exists.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-security-put-user-managed-service-account
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-security-put-user-managed-service-account
products:
  - Elasticsearch
---

# Create user-managed service accounts

Availability: Planned

## Paths

- `PUT` `/_security/service/{namespace}/{service}`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#bearerauth)

#### Path Parameters

- `namespace` (string)
  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)
  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.

## Description

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](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/service-accounts)

## Query String Parameters

- `refresh` (enum Refresh · default: wait_for)
  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.
  Values: `true`, `false`, `wait_for`

## Request Body

`application/json`

- `roles` ([] 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 · default: true) — optional
  Whether the account can authenticate.
Tokens can still be created for a disabled account; they just cannot be used until the account is enabled.
- `description` (string) — optional
  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.

## Response

`application/json`

- `created` (boolean)
  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`.
## Code Examples

#### Console

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

#### JavaScript

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

#### Python

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

#### curl

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

#### PHP

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

#### Ruby

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

## Response Examples

#### Put user managed service account response example1

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

```json
{
  "created": true
}
```