> For the complete documentation index, see [llms.txt](https://docs.enclaive.cloud/vault/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enclaive.cloud/vault/api/secrets-engines/identity/group-alias.md).

# group-alias

### Create a group alias <a href="#create-a-group-alias" id="create-a-group-alias"></a>

This endpoint creates or updates a group alias.

| Method | Path                    |
| ------ | ----------------------- |
| `POST` | `/identity/group-alias` |

#### Parameters <a href="#parameters" id="parameters"></a>

* `name` `(string: entity-<UUID>)` – Name of the group alias.
* `id` `(string: <optional>)` - ID of the group alias. If set, updates the corresponding existing group alias.
* `mount_accessor` `(string: "")` – Mount accessor which this alias belongs to.
* `canonical_id` `(string: "")` - ID of the group to which this is an alias.

#### Sample payload <a href="#sample-payload" id="sample-payload"></a>

```json
{
  "canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b",
  "mount_accessor": "auth_github_232a90dc",
  "name": "dev-team"
}
```

#### Sample request <a href="#sample-request" id="sample-request"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/group-alias
```

#### Sample response <a href="#sample-response" id="sample-response"></a>

```json
{
  "data": {
    "canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b",
    "id": "ca726050-d8ac-6f1f-4210-3b5c5b613824"
  }
}
```

### Update group alias by ID <a href="#update-group-alias-by-id" id="update-group-alias-by-id"></a>

This endpoint is used to update an existing group alias.

| Method | Path                           |
| ------ | ------------------------------ |
| `POST` | `/identity/group-alias/id/:id` |

#### Parameters <a href="#parameters-1" id="parameters-1"></a>

* `id` `(string: <optional>)` - ID of the group alias.
* `name` `(string: entity-<UUID>)` – Name of the group alias.
* `mount_accessor` `(string: "")` – Mount accessor which this alias belongs to.
* `canonical_id` `(string: "")` - ID of the group to which this is an alias.

#### Sample payload <a href="#sample-payload-1" id="sample-payload-1"></a>

```json
{
  "canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b",
  "mount_accessor": "auth_github_232a90dc",
  "name": "dev-team"
}
```

#### Sample request <a href="#sample-request-1" id="sample-request-1"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/group-alias/id/ca726050-d8ac-6f1f-4210-3b5c5b613824
```

#### Sample response <a href="#sample-response-1" id="sample-response-1"></a>

```json
{
  "data": {
    "canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b",
    "id": "ca726050-d8ac-6f1f-4210-3b5c5b613824"
  }
}
```

### Read group alias by ID <a href="#read-group-alias-by-id" id="read-group-alias-by-id"></a>

This endpoint queries the group alias by its identifier.

| Method | Path                           |
| ------ | ------------------------------ |
| `GET`  | `/identity/group-alias/id/:id` |

#### Parameters <a href="#parameters-2" id="parameters-2"></a>

* `id` `(string: <required>)` – ID of the group alias.

#### Sample request <a href="#sample-request-2" id="sample-request-2"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/identity/group-alias/id/ca726050-d8ac-6f1f-4210-3b5c5b613824
```

#### Sample response <a href="#sample-response-2" id="sample-response-2"></a>

```json
{
  "data": {
    "canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b",
    "creation_time": "2017-11-13T20:09:41.661694Z",
    "id": "ca726050-d8ac-6f1f-4210-3b5c5b613824",
    "last_update_time": "2017-11-13T20:09:41.661694Z",
    "merged_from_canonical_ids": null,
    "metadata": null,
    "mount_accessor": "auth_github_232a90dc",
    "mount_path": "",
    "mount_type": "github",
    "name": "dev-team"
  }
}
```

### Delete group alias by ID <a href="#delete-group-alias-by-id" id="delete-group-alias-by-id"></a>

This endpoint deletes a group alias.

| Method   | Path                           |
| -------- | ------------------------------ |
| `DELETE` | `/identity/group-alias/id/:id` |

### Parameters <a href="#parameters-3" id="parameters-3"></a>

* `id` `(string: <required>)` – ID of the group alias.

#### Sample request <a href="#sample-request-3" id="sample-request-3"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/group-alias/id/ca726050-d8ac-6f1f-4210-3b5c5b613824
```

### List group alias by ID <a href="#list-group-alias-by-id" id="list-group-alias-by-id"></a>

This endpoint returns a list of available group aliases by their identifiers.

| Method | Path                                 |
| ------ | ------------------------------------ |
| `LIST` | `/identity/group-alias/id`           |
| `GET`  | `/identity/group-alias/id?list=true` |

#### Sample request <a href="#sample-request-4" id="sample-request-4"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/identity/group-alias/id
```

#### Sample response <a href="#sample-response-3" id="sample-response-3"></a>

```json
{
  "data": {
    "keys": ["ca726050-d8ac-6f1f-4210-3b5c5b613824"]
  }
}
```