Home

Identity

Create a new alias.

post
Body
namestringRequired

Name of the alias.

canonical_idstringRequired

Entity ID the alias should be associated with.

mount_accessorstringRequired

Accessor of the mount that the alias belongs to.

Responses
200
Alias successfully created.
application/json
post
POST /v1/identity/alias HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 172

{
  "name": "web-entity-alias",
  "canonical_id": "f8caa34f-5914-5a27-13b3-1be6bdf562b9",
  "mount_accessor": "auth_userpass_12345678",
  "custom_metadata": {
    "team": "dev",
    "location": "IN"
  }
}
{
  "data": {
    "id": "bda7a8b6-dbe9-4622-3a34-8904589d3a17",
    "name": "web-entity-alias",
    "mount_type": "userpass",
    "canonical_id": "f8caa34f-5914-5a27-13b3-1be6bdf562b9",
    "custom_metadata": {
      "team": "dev",
      "location": "IN"
    }
  }
}

List all the alias IDs

get
Query parameters
liststring · enumRequired

Must be set to true

Possible values:
Responses
200
Successfully listed alias IDs
application/json
Responseany
get
GET /v1/identity/alias/id HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "request_id": "f31e1be4-bae6-8709-b173-69c2e7846211",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "keys": [
      "bda7a8b6-dbe9-4622-3a34-8904589d3a17",
      "cbe1d3af-d9cd-43b9-9e29-54a17dc830d9"
    ]
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Read an alias by ID

get
Path parameters
idstringRequired

ID of the alias

Responses
200
Alias details retrieved successfully.
application/json
get
GET /v1/identity/alias/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "request_id": "a3d8e7f2-25be-abc1-3cd4-84792cbbd9f5",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "id": "bda7a8b6-dbe9-4622-3a34-8904589d3a17",
    "name": "my-alias",
    "mount_type": "userpass",
    "canonical_id": "abcd1234-ef56-7890-ghij-klmnopqrstuv",
    "custom_metadata": {}
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Update an alias by ID

post
Path parameters
idstringRequired

ID of the alias

Body
canonical_idstringOptional

Entity ID to which this alias should be tied to

entity_idstringOptional

Entity ID to which this alias should be tied to. This field is deprecated in favor of 'canonical_id'.

mount_accessorstringOptional

Mount accessor to which this alias belongs to

namestringOptional

Name of the alias

Responses
200
Alias updated successfully.
application/json
post
POST /v1/identity/alias/id/{id} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 170

{
  "name": "my-updated-alias",
  "mount_accessor": "auth_userpass_12345678",
  "canonical_id": "abcd1234-ef56-7890-ghij-klmnopqrstuv",
  "custom_metadata": {
    "department": "engineering"
  }
}
{
  "data": {
    "id": "bda7a8b6-dbe9-4622-3a34-8904589d3a17",
    "name": "my-updated-alias",
    "mount_type": "userpass",
    "canonical_id": "abcd1234-ef56-7890-ghij-klmnopqrstuv",
    "custom_metadata": {
      "department": "engineering"
    }
  }
}

Delete an alias by ID

delete
Path parameters
idstringRequired

ID of the alias

Responses
204
Alias deleted successfully. No content is returned.
delete
DELETE /v1/identity/alias/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

Create a new entity

post
Body
disabledbooleanOptional

If set true, tokens tied to this identity will not be able to be used (but will not be revoked).

idstringOptional

ID of the entity. If set, updates the corresponding existing entity.

metadataobject · kvpairsOptional

Metadata to be associated with the entity. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: vault metadata=key1=value1 metadata=key2=value2

namestringOptional

Name of the entity

policiesstring[]Optional

Policies to be tied to the entity.

Responses
200
Entity created successfully.
application/json
Responseany
post
POST /v1/identity/entity HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 110

{
  "name": "web-user-entity",
  "metadata": {
    "team": "devops",
    "location": "us-west"
  },
  "policies": [
    "default",
    "dev-team"
  ]
}
{
  "data": {
    "id": "a1234567-b890-4def-8123-abcdef123456",
    "name": "web-user-entity",
    "metadata": {
      "team": "devops",
      "location": "us-west"
    },
    "policies": [
      "default",
      "dev-team"
    ]
  }
}

Create a new alias for the entity

post
Body
canonical_idstringOptional

Entity ID to which this alias belongs

custom_metadataobject · kvpairsOptional

User provided key-value pairs

entity_idstringOptional

Entity ID to which this alias belongs. This field is deprecated, use canonical_id.

idstringOptional

ID of the entity alias. If set, updates the corresponding entity alias.

mount_accessorstringOptional

Mount accessor to which this alias belongs to; unused for a modify

namestringOptional

Name of the alias; unused for a modify

Responses
200
Alias successfully created.
application/json
Responseany
post
POST /v1/identity/entity-alias HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 182

{
  "name": "login-alias-web",
  "canonical_id": "ef42e3d6-8121-4211-b7f4-123456789abc",
  "mount_accessor": "auth_userpass_a1b2c3d4",
  "custom_metadata": {
    "environment": "prod",
    "region": "eu-west"
  }
}
{
  "data": {
    "id": "12e458c2-6df4-44b3-bbea-928a1e0073b5",
    "name": "login-alias-web",
    "mount_type": "userpass",
    "canonical_id": "ef42e3d6-8121-4211-b7f4-123456789abc",
    "custom_metadata": {
      "environment": "prod",
      "region": "eu-west"
    }
  }
}

List all the alias IDs for the entity

get
Query parameters
liststring · enumRequired

Must be set to true

Possible values:
Responses
200
Successfully listed alias IDs.
application/json
Responseany
get
GET /v1/identity/entity-alias/id HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "request_id": "a11b22c3-d4ef-5678-9abc-000000000000",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "keys": [
      "bda7a8b6-dbe9-4622-3a34-8904589d3a17",
      "cbe1d3af-d9cd-43b9-9e29-54a17dc830d9"
    ]
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Read an alias by ID for the entity

get
Path parameters
idstringRequired

ID of the alias

Responses
200
Alias details retrieved successfully.
application/json
Responseany
get
GET /v1/identity/entity-alias/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "request_id": "1234abcd-ef56-7890-gh12-ijklmnopqrst",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
    "name": "my-entity-alias",
    "mount_type": "userpass",
    "canonical_id": "canonical-123",
    "custom_metadata": {
      "role": "devops"
    }
  }
}

Update an alias by ID for the entity

post
Path parameters
idstringRequired

ID of the alias

Body
canonical_idstringOptional

Entity ID to which this alias should be tied to

custom_metadataobject · kvpairsOptional

User provided key-value pairs

entity_idstringOptional

Entity ID to which this alias belongs to. This field is deprecated, use canonical_id.

mount_accessorstringOptional

(Unused)

namestringOptional

(Unused)

Responses
200
Alias updated successfully.
application/json
Responseany
post
POST /v1/identity/entity-alias/id/{id} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 143

{
  "name": "updated-alias-name",
  "mount_accessor": "auth_userpass_98765432",
  "canonical_id": "canonical-123",
  "custom_metadata": {
    "team": "engineering"
  }
}
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
    "name": "updated-alias-name",
    "mount_type": "userpass",
    "canonical_id": "canonical-123",
    "custom_metadata": {
      "team": "engineering"
    }
  }
}

Delete an alias by ID for the entity

delete
Path parameters
idstringRequired

ID of the alias

Responses
204
Alias deleted successfully. No content returned.
delete
DELETE /v1/identity/entity-alias/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

Delete all of the entities

post
Body
entity_idsstring[]Optional

Entity IDs to delete

Responses
200
Entities deleted successfully.
application/json
Responseany
post
POST /v1/identity/entity/batch-delete HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "entity_ids": [
    "entity-123",
    "entity-456",
    "entity-789"
  ]
}
{
  "request_id": "1234abcd-ef56-7890-gh12-ijklmnopqrst",
  "deleted_ids": [
    "entity-123",
    "entity-456",
    "entity-789"
  ],
  "errors": []
}

List all the entity IDs

get
Query parameters
liststring · enumRequired

Must be set to true

Example: truePossible values:
Responses
200
Successfully retrieved the list of entity IDs.
application/json
Responseany
get
GET /v1/identity/entity/id HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "request_id": "d34db33f-b6e1-4ea7-8180-9827e9f8e5ac",
  "data": {
    "keys": [
      "entity-123",
      "entity-456",
      "entity-789"
    ]
  }
}

Read an entity by ID

get
Path parameters
idstringRequired

ID of the entity. If set, updates the corresponding existing entity.

Responses
200
Entity details retrieved successfully.
application/json
Responseany
get
GET /v1/identity/entity/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "request_id": "dd1f7b72-05d4-4234-b8e5-cb61e2dfb942",
  "data": {
    "id": "a1b2c3d4",
    "name": "developer-entity",
    "metadata": {
      "department": "engineering"
    }
  }
}

Update an entity by ID

post
Path parameters
idstringRequired

ID of the entity. If set, updates the corresponding existing entity.

Body
disabledbooleanOptional

If set true, tokens tied to this identity will not be able to be used (but will not be revoked).

metadataobject · kvpairsOptional

Metadata to be associated with the entity. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: vault metadata=key1=value1 metadata=key2=value2

namestringOptional

Name of the entity

policiesstring[]Optional

Policies to be tied to the entity.

Responses
200
Entity updated successfully.
application/json
Responseany
post
POST /v1/identity/entity/id/{id} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "name": "updated-entity",
  "metadata": {
    "role": "admin"
  }
}
{
  "data": {
    "id": "a1b2c3d4",
    "name": "updated-entity",
    "metadata": {
      "role": "admin"
    }
  }
}

Delete an entity by ID

delete
Path parameters
idstringRequired

ID of the entity. If set, updates the corresponding existing entity.

Responses
204
Entity deleted successfully. No content is returned.
delete
DELETE /v1/identity/entity/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

Merge two or more entities together

post
Body
conflicting_alias_ids_to_keepstring[]Optional

Alias IDs to keep in case of conflicting aliases. Ignored if no conflicting aliases found

forcebooleanOptional

Setting this will follow the 'mine' strategy for merging MFA secrets. If there are secrets of the same type both in entities that are merged from and in entity into which all others are getting merged, secrets in the destination will be unaltered. If not set, this API will throw an error containing all the conflicts.

from_entity_idsstring[]Optional

Entity IDs which need to get merged

to_entity_idstringOptional

Entity ID into which all the other entities need to get merged

Responses
200
Entities merged successfully.
application/json
Responseany
post
POST /v1/identity/entity/merge HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 125

{
  "primary_entity_id": "entity-001",
  "secondary_entity_ids": [
    "entity-002",
    "entity-003"
  ],
  "metadata": {
    "source": "admin-initiated"
  }
}
{
  "request_id": "78e1b3f6-482b-47f6-90a1-c5b6dc94d9f1",
  "data": {
    "id": "entity-001",
    "merged_from": [
      "entity-002",
      "entity-003"
    ],
    "metadata": {
      "source": "admin-initiated"
    }
  }
}

List all the entity names

get
Query parameters
liststring · enumRequired

Must be set to true

Example: truePossible values:
Responses
200
A list of entity names was successfully retrieved.
application/json
get
GET /v1/identity/entity/name HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "request_id": "8df8b7f3-4c1a-45b8-b23a-e4c1b61c5f95",
  "data": {
    "keys": [
      "developer-entity",
      "admin-entity",
      "viewer-entity"
    ]
  }
}

Read an entity by name

get
Path parameters
namestringRequired

Name of the entity

Responses
200
Entity retrieved successfully.
application/json
Responseany
get
GET /v1/identity/entity/name/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "request_id": "d7c78b49-235b-4e3a-b2ef-237bb9a1fe3e",
  "data": {
    "id": "3dfb7a63-d826-4b8d-97c5-b31fc109e8c5",
    "name": "developer-entity",
    "metadata": {
      "team": "engineering"
    },
    "policies": [
      "default",
      "admin"
    ]
  }
}

Update an entity by name

post
Path parameters
namestringRequired

Name of the entity

Body
disabledbooleanOptional

If set true, tokens tied to this identity will not be able to be used (but will not be revoked).

idstringOptional

ID of the entity. If set, updates the corresponding existing entity.

metadataobject · kvpairsOptional

Metadata to be associated with the entity. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: vault metadata=key1=value1 metadata=key2=value2

policiesstring[]Optional

Policies to be tied to the entity.

Responses
200
Entity updated successfully.
application/json
Responseany
post
POST /v1/identity/entity/name/{name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "metadata": {
    "team": "platform"
  },
  "policies": [
    "developer",
    "audit"
  ]
}
{
  "data": {
    "id": "3dfb7a63-d826-4b8d-97c5-b31fc109e8c5",
    "name": "developer-entity",
    "metadata": {
      "team": "platform"
    },
    "policies": [
      "developer",
      "audit"
    ]
  }
}

Delete an entity by name

delete
Path parameters
namestringRequired

Name of the entity

Responses
204
Entity deleted successfully. No content returned.
delete
DELETE /v1/identity/entity/name/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

Create a new group

post
Body
idstringOptional

ID of the group. If set, updates the corresponding existing group.

member_entity_idsstring[]Optional

Entity IDs to be assigned as group members.

member_group_idsstring[]Optional

Group IDs to be assigned as group members.

metadataobject · kvpairsOptional

Metadata to be associated with the group. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: vault metadata=key1=value1 metadata=key2=value2

namestringOptional

Name of the group.

policiesstring[]Optional

Policies to be tied to the group.

typestringOptional

Type of the group, 'internal' or 'external'. Defaults to 'internal'

Responses
200
Group created successfully.
application/json
Responseany
post
POST /v1/identity/group HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 97

{
  "name": "dev-team",
  "metadata": {
    "project": "internal-tools"
  },
  "policies": [
    "read-only",
    "dev-access"
  ]
}
{
  "data": {
    "id": "c1f90532-f01b-4fcd-8029-8f3ad5a58f6d",
    "name": "dev-team",
    "metadata": {
      "project": "internal-tools"
    },
    "policies": [
      "read-only",
      "dev-access"
    ]
  }
}

Create a new group alias, or update an existing one

post
Body
canonical_idstringOptional

ID of the group to which this is an alias.

idstringOptional

ID of the group alias.

mount_accessorstringOptional

Mount accessor to which this alias belongs to.

namestringOptional

Alias of the group.

Responses
200
Group alias created or updated successfully.
application/json
Responseany
post
POST /v1/identity/group-alias HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 151

{
  "name": "ldap-alias-devs",
  "mount_accessor": "ldap_12345678",
  "canonical_id": "group-abc123-def456-ghi789",
  "custom_metadata": {
    "region": "APAC",
    "env": "dev"
  }
}
{
  "data": {
    "id": "alias-9876-5432-10ab",
    "name": "ldap-alias-devs",
    "mount_type": "ldap",
    "canonical_id": "group-abc123-def456-ghi789",
    "custom_metadata": {
      "region": "APAC",
      "env": "dev"
    }
  }
}

List all the group alias IDs

get
Query parameters
liststring · enumRequired

Must be set to true

Example: truePossible values:
Responses
200
OK
application/json
Responseany
get
GET /v1/identity/group-alias/id HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "group_alias_ids": [
    "alias1",
    "alias2",
    "alias3"
  ]
}

Read a group alias by its ID

get
Path parameters
idstringRequired

ID of the group alias.

Example: alias123
Responses
200
OK
application/json
Responseany
get
GET /v1/identity/group-alias/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "id": "alias123",
  "name": "Group Alias Name",
  "description": "A description of the group alias."
}

Update a group alias by its ID

post
Path parameters
idstringRequired

ID of the group alias.

Example: alias123
Body
canonical_idstringOptional

ID of the group to which this is an alias.

mount_accessorstringOptional

Mount accessor to which this alias belongs to.

namestringOptional

Alias of the group.

Responses
200
OK
application/json
Responseany
post
POST /v1/identity/group-alias/id/{id} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 85

{
  "name": "Updated Alias Name",
  "description": "Updated description of the group alias."
}
{
  "id": "alias123",
  "name": "Updated Alias Name",
  "description": "Updated description of the group alias."
}

Delete a group alias by its ID

delete
Path parameters
idstringRequired

ID of the group alias.

Example: alias123
Responses
204
No content - The alias was successfully deleted.
delete
DELETE /v1/identity/group-alias/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

List all the group IDs

get
Query parameters
liststring · enumRequired

Must be set to true

Example: truePossible values:
Responses
200
List of group IDs retrieved successfully.
application/json
Responseany
get
GET /v1/identity/group/id HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "groups": [
    {
      "id": "group1"
    },
    {
      "id": "group2"
    },
    {
      "id": "group3"
    }
  ]
}

Read group details by ID

get
Path parameters
idstringRequired

ID of the group. If set, updates the corresponding existing group.

Example: group123
Responses
200
Group retrieved successfully.
application/json
Responseany
get
GET /v1/identity/group/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "id": "group123",
  "name": "Admins",
  "description": "Administrators group"
}

Update an existing group by ID

post
Path parameters
idstringRequired

ID of the group. If set, updates the corresponding existing group.

Example: group123
Body
member_entity_idsstring[]Optional

Entity IDs to be assigned as group members.

member_group_idsstring[]Optional

Group IDs to be assigned as group members.

metadataobject · kvpairsOptional

Metadata to be associated with the group. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: vault metadata=key1=value1 metadata=key2=value2

namestringOptional

Name of the group.

policiesstring[]Optional

Policies to be tied to the group.

typestringOptional

Type of the group, 'internal' or 'external'. Defaults to 'internal'

Responses
200
Group updated successfully.
application/json
Responseany
post
POST /v1/identity/group/id/{id} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "name": "New Group Name",
  "description": "Updated description of the group"
}
{
  "id": "group123",
  "name": "New Group Name",
  "description": "Updated description of the group"
}

Delete a group by ID

delete
Path parameters
idstringRequired

ID of the group. If set, updates the corresponding existing group.

Example: group123
Responses
204
No content - The group was deleted successfully.
delete
DELETE /v1/identity/group/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

List all group names

get
Query parameters
liststring · enumRequired

Must be set to true

Example: truePossible values:
Responses
200
Successfully retrieved list of group names.
application/json
Responseany
get
GET /v1/identity/group/name HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "groups": [
    {
      "name": "Admins"
    },
    {
      "name": "Developers"
    },
    {
      "name": "Support"
    }
  ]
}

Read a group by its name

get
Path parameters
namestringRequired

Name of the group.

Example: Admins
Responses
200
Group retrieved successfully.
application/json
Responseany
get
GET /v1/identity/group/name/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "name": "Admins",
  "id": "group123",
  "description": "Group for admin users"
}

Update an existing group by its name

post
Path parameters
namestringRequired

Name of the group.

Example: Admins
Body
idstringOptional

ID of the group. If set, updates the corresponding existing group.

member_entity_idsstring[]Optional

Entity IDs to be assigned as group members.

member_group_idsstring[]Optional

Group IDs to be assigned as group members.

metadataobject · kvpairsOptional

Metadata to be associated with the group. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: vault metadata=key1=value1 metadata=key2=value2

policiesstring[]Optional

Policies to be tied to the group.

typestringOptional

Type of the group, 'internal' or 'external'. Defaults to 'internal'

Responses
200
Group updated successfully.
application/json
Responseany
post
POST /v1/identity/group/name/{name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "description": "Updated group for admin users"
}
{
  "name": "Admins",
  "id": "group123",
  "description": "Updated group for admin users"
}

Delete a group by its name

delete
Path parameters
namestringRequired

Name of the group.

Example: Admins
Responses
204
No content - The group was deleted successfully.
delete
DELETE /v1/identity/group/name/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

Query entities based on various properties

post
Body
alias_idstringOptional

ID of the alias.

alias_mount_accessorstringOptional

Accessor of the mount to which the alias belongs to. This should be supplied in conjunction with 'alias_name'.

alias_namestringOptional

Name of the alias. This should be supplied in conjunction with 'alias_mount_accessor'.

idstringOptional

ID of the entity.

namestringOptional

Name of the entity.

Responses
200
Matching entities retrieved successfully.
application/json
Responseany
post
POST /v1/identity/lookup/entity HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "alias": "john.doe"
}
{
  "entities": [
    {
      "id": "1234",
      "alias": "john.doe",
      "name": "John Doe",
      "metadata": {
        "department": "Engineering"
      }
    }
  ]
}

Query groups based on various properties

post
Body
alias_idstringOptional

ID of the alias.

alias_mount_accessorstringOptional

Accessor of the mount to which the alias belongs to. This should be supplied in conjunction with 'alias_name'.

alias_namestringOptional

Name of the alias. This should be supplied in conjunction with 'alias_mount_accessor'.

idstringOptional

ID of the group.

namestringOptional

Name of the group.

Responses
200
Matching groups retrieved successfully.
application/json
Responseany
post
POST /v1/identity/lookup/group HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "name": "Admins"
}
{
  "groups": [
    {
      "id": "group-123",
      "name": "Admins",
      "description": "Administrative users group"
    }
  ]
}

List login enforcement rules

get
Query parameters
liststring · enumRequired

Must be set to true

Example: truePossible values:
Responses
200
MFA login enforcements retrieved successfully.
application/json
Responseany
get
GET /v1/identity/mfa/login-enforcement HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "enforcements": [
    {
      "id": "rule-001",
      "name": "Require MFA for admins",
      "condition": "role == admin",
      "enabled": true
    },
    {
      "id": "rule-002",
      "name": "MFA for all users",
      "condition": "true",
      "enabled": false
    }
  ]
}

Read a login enforcement configuration

get

Retrieve details of a specific MFA login enforcement rule by name.

Path parameters
namestringRequired

Name for this login enforcement configuration

Example: require-admin-mfa
Responses
200
Login enforcement rule retrieved successfully.
application/json
Responseany
get
GET /v1/identity/mfa/login-enforcement/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "id": "rule-001",
  "name": "require-admin-mfa",
  "condition": "role == admin",
  "enabled": true
}

Create or update a login enforcement configuration

post

Create a new or update an existing MFA login enforcement rule.

Path parameters
namestringRequired

Name for this login enforcement configuration

Example: require-admin-mfa
Body
auth_method_accessorsstring[]Optional

Array of auth mount accessor IDs

auth_method_typesstring[]Optional

Array of auth mount types

identity_entity_idsstring[]Optional

Array of identity entity IDs

identity_group_idsstring[]Optional

Array of identity group IDs

mfa_method_idsstring[]Required

Array of Method IDs that determine what methods will be enforced

Responses
200
Login enforcement rule created or updated successfully.
application/json
Responseany
post
POST /v1/identity/mfa/login-enforcement/{name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "name": "require-admin-mfa",
  "condition": "role == admin",
  "enabled": true
}
{
  "id": "rule-001",
  "name": "require-admin-mfa",
  "condition": "role == admin",
  "enabled": true
}

Delete a login enforcement configuration

delete

Remove an existing MFA login enforcement rule identified by its name.

Path parameters
namestringRequired

Name for this login enforcement configuration

Example: require-admin-mfa
Responses
204
Login enforcement deleted successfully. No content returned.
delete
DELETE /v1/identity/mfa/login-enforcement/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

List MFA method configurations for all MFA methods

get

Retrieve a list of all configured Multi-Factor Authentication (MFA) methods in the system.

Query parameters
liststring · enumRequired

Must be set to true

Example: truePossible values:
Responses
200
A list of configured MFA methods
application/json
Responseany
get
GET /v1/identity/mfa/method HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "methods": [
    {
      "name": "totp",
      "enabled": true,
      "description": "Time-based One-Time Password (TOTP)"
    },
    {
      "name": "webauthn",
      "enabled": false,
      "description": "WebAuthn biometric authentication"
    }
  ]
}

List Duo MFA method configurations

get

Retrieve the configuration for the Duo MFA method if it is enabled and configured.

Query parameters
liststring · enumRequired

Must be set to true

Example: truePossible values:
Responses
200
Duo MFA configuration details
application/json
Responseany
get
GET /v1/identity/mfa/method/duo HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "method": "duo",
  "enabled": true,
  "integration_key": "DIXXXXXXXXXXXXXXXXXX",
  "api_hostname": "api-XXXXXXXX.duosecurity.com",
  "description": "Duo Security multi-factor authentication"
}

Read the current configuration for the given MFA method

get
Path parameters
method_idstringRequired

The unique identifier for this MFA method.

Responses
200
Successfully retrieved Duo MFA configuration
application/json
Responseany
get
GET /v1/identity/mfa/method/duo/{method_id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "method_id": "duo-primary",
  "method": "duo",
  "enabled": true,
  "integration_key": "DIXXXXXXXXXXXXXXXXXX",
  "api_hostname": "api-XXXXXXX.duosecurity.com",
  "description": "Primary Duo MFA config for admins"
}

Delete a configuration for the given MFA method

delete
Path parameters
method_idstringRequired

The unique identifier for this MFA method.

Responses
204
Successfully deleted. No content returned.
delete
DELETE /v1/identity/mfa/method/duo/{method_id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

List MFA method configurations for the given MFA method

get
Query parameters
liststring · enumRequired

Must be set to true

Possible values:
Responses
200
Successfully retrieved Okta MFA method configurations
application/json
Responseany[]
get
GET /v1/identity/mfa/method/okta HTTP/1.1
Host: localhost:8200
Accept: */*

[
  {
    "method_id": "okta-primary",
    "method": "okta",
    "enabled": true,
    "okta_domain": "https://dev-123456.okta.com",
    "client_id": "0oab4exampleID",
    "description": "Primary Okta MFA config"
  },
  {
    "method_id": "okta-secondary",
    "method": "okta",
    "enabled": false,
    "okta_domain": "https://dev-789012.okta.com",
    "client_id": "0oab5exampleID",
    "description": "Backup Okta configuration"
  }
]

Read the current configuration for the given MFA method

get
Path parameters
method_idstringRequired

The unique identifier for this MFA method.

Responses
200
Successfully retrieved the Okta MFA configuration
application/json
Responseany
get
GET /v1/identity/mfa/method/okta/{method_id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "method_id": "okta-primary",
  "method": "okta",
  "enabled": true,
  "okta_domain": "https://dev-123456.okta.com",
  "client_id": "0oab4exampleID",
  "description": "Primary Okta MFA config"
}

Update or create a configuration for the given MFA method

post
Path parameters
method_idstringRequired

The unique identifier for this MFA method.

Body
api_tokenstringOptional

Okta API key.

base_urlstringOptional

The base domain to use for the Okta API. When not specified in the configuration, "okta.com" is used.

method_namestringOptional

The unique name identifier for this MFA method.

org_namestringOptional

Name of the organization to be used in the Okta API.

primary_emailbooleanOptional

If true, the username will only match the primary email for the account. Defaults to false.

productionbooleanOptional

(DEPRECATED) Use base_url instead.

username_formatstringOptional

A template string for mapping Identity names to MFA method names. Values to substitute should be placed in {{}}. For example, "{{entity.name}}@example.com". If blank, the Entity's name field will be used as-is.

Responses
200
Successfully configured the Okta MFA method
application/json
Responseany
post
POST /v1/identity/mfa/method/okta/{method_id} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 191

{
  "method_id": "okta-primary",
  "okta_domain": "https://dev-123456.okta.com",
  "client_id": "0oab4exampleID",
  "client_secret": "supersecretvalue",
  "enabled": true,
  "description": "Updated config for Okta"
}
{
  "method_id": "okta-primary",
  "method": "okta",
  "enabled": true,
  "okta_domain": "https://dev-123456.okta.com",
  "client_id": "0oab4exampleID",
  "description": "Updated config for Okta"
}

Delete a configuration for the given MFA method

delete
Path parameters
method_idstringRequired

The unique identifier for this MFA method.

Responses
204
Configuration deleted successfully
delete
DELETE /v1/identity/mfa/method/okta/{method_id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

List MFA method configurations for PingID

get
Query parameters
liststring · enumRequired

Must be set to true

Possible values:
Responses
200
Successfully retrieved PingID MFA method configurations
application/json
Responseany
get
GET /v1/identity/mfa/method/pingid HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "methods": [
    {
      "method_id": "pingid-primary",
      "method": "pingid",
      "enabled": true,
      "pingid_environment_id": "abc123",
      "description": "Primary PingID method"
    },
    {
      "method_id": "pingid-secondary",
      "method": "pingid",
      "enabled": false,
      "pingid_environment_id": "xyz789",
      "description": "Backup PingID method"
    }
  ]
}

Read the current configuration for the given PingID MFA method

get
Path parameters
method_idstringRequired

The unique identifier for the PingID MFA method configuration.

Responses
200
Successfully retrieved the PingID method configuration
application/json
Responseany
get
GET /v1/identity/mfa/method/pingid/{method_id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "method_id": "pingid-primary",
  "method": "pingid",
  "enabled": true,
  "pingid_environment_id": "env-123",
  "description": "Primary PingID configuration"
}

Create or update a configuration for the given PingID MFA method

post
Path parameters
method_idstringRequired

The unique identifier for the PingID MFA method configuration.

Body
method_namestringOptional

The unique name identifier for this MFA method.

settings_file_base64stringOptional

The settings file provided by Ping, Base64-encoded. This must be a settings file suitable for third-party clients, not the PingID SDK or PingFederate.

username_formatstringOptional

A template string for mapping Identity names to MFA method names. Values to subtitute should be placed in {{}}. For example, "{{alias.name}}@example.com". Currently-supported mappings: alias.name: The name returned by the mount configured via the mount_accessor parameter If blank, the Alias's name field will be used as-is.

Responses
200
PingID MFA method configuration updated successfully
application/json
Responseany
post
POST /v1/identity/mfa/method/pingid/{method_id} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 124

{
  "method_id": "pingid-primary",
  "pingid_environment_id": "env-123",
  "enabled": true,
  "description": "Updated PingID configuration"
}
{
  "method_id": "pingid-primary",
  "method": "pingid",
  "enabled": true,
  "pingid_environment_id": "env-123",
  "description": "Updated PingID configuration"
}

Delete a configuration for the given PingID MFA method

delete
Path parameters
method_idstringRequired

The unique identifier for the PingID MFA method configuration.

Responses
404
Configuration not found
application/json
delete
DELETE /v1/identity/mfa/method/pingid/{method_id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "error": "Not Found",
  "message": "No configuration found for method_id: pingid-primary"
}

List MFA method configurations for the TOTP method

get
Query parameters
liststring · enumRequired

Must be set to 'true' to list configurations

Possible values:
Responses
200
List of TOTP MFA method configurations
application/json
Responseany[]
get
GET /v1/identity/mfa/method/totp HTTP/1.1
Host: localhost:8200
Accept: */*

[
  {
    "method_id": "totp-default",
    "method": "totp",
    "enabled": true,
    "issuer": "vault-auth",
    "label": "Vault TOTP MFA",
    "period": 30,
    "digits": 6
  }
]

Delete a TOTP secret for the given MFA method ID on the given entity

post
Body
entity_idstringRequired

Identifier of the entity from which the MFA method secret needs to be removed.

method_idstringRequired

The unique identifier for this MFA method.

Responses
200
Secret destroyed successfully
application/json
Responseany
post
POST /v1/identity/mfa/method/totp/admin-destroy HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 79

{
  "method_id": "totp-default",
  "entity_id": "f398b240-ef4e-4b4a-a1ce-6be5f0e25d52"
}
{
  "success": true,
  "message": "TOTP secret destroyed for entity f398b240-ef4e-4b4a-a1ce-6be5f0e25d52"
}

Update or create TOTP secret for the given method ID as admin on the given entity.

post
Body
entity_idstringRequired

Entity ID on which the generated secret needs to get stored.

method_idstringRequired

The unique identifier for this MFA method.

Responses
200
TOTP secret created or updated successfully
application/json
Responseany
post
POST /v1/identity/mfa/method/totp/admin-generate HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 79

{
  "method_id": "totp-primary",
  "entity_id": "ee2bb4a2-cc30-4e55-a2b6-7cb8dc0ed1f4"
}
{
  "success": true,
  "message": "TOTP secret generated",
  "totp_url": "otpauth://totp/Example:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=Example"
}

Update or create TOTP secret for the given method ID on the given entity.

post
Body
method_idstringRequired

The unique identifier for this MFA method.

Responses
200
TOTP secret created or updated successfully
application/json
Responseany
post
POST /v1/identity/mfa/method/totp/generate HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 79

{
  "method_id": "totp-primary",
  "entity_id": "2e7b8a42-78fc-43d1-bf04-4fcf8c2c3d61"
}
{
  "success": true,
  "message": "TOTP secret generated",
  "totp_url": "otpauth://totp/Example:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=Example"
}

Read the current configuration for the given TOTP MFA method

get
Path parameters
method_idstringRequired

The unique identifier for this TOTP MFA method.

Responses
200
Configuration retrieved successfully
application/json
Responseany
get
GET /v1/identity/mfa/method/totp/{method_id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "method_id": "totp-123",
  "issuer": "MyCompany",
  "label": "[email protected]",
  "algorithm": "SHA1",
  "digits": 6,
  "period": 30
}

Create or update the configuration for the given TOTP MFA method

post
Path parameters
method_idstringRequired

The unique identifier for this TOTP MFA method.

Body
algorithmstringOptional

The hashing algorithm used to generate the TOTP token. Options include SHA1, SHA256 and SHA512.

Default: SHA1
digitsintegerOptional

The number of digits in the generated TOTP token. This value can either be 6 or 8.

Default: 6
issuerstringOptional

The name of the key's issuing organization.

key_sizeintegerOptional

Determines the size in bytes of the generated key.

Default: 20
max_validation_attemptsintegerOptional

Max number of allowed validation attempts.

method_namestringOptional

The unique name identifier for this MFA method.

periodinteger · secondsOptional

The length of time used to generate a counter for the TOTP token calculation.

Default: 30
qr_sizeintegerOptional

The pixel size of the generated square QR code.

Default: 200
skewintegerOptional

The number of delay periods that are allowed when validating a TOTP token. This value can either be 0 or 1.

Default: 1
Responses
200
Configuration created or updated successfully
application/json
Responseany
post
POST /v1/identity/mfa/method/totp/{method_id} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "issuer": "MyCompany",
  "label": "[email protected]",
  "algorithm": "SHA1",
  "digits": 6,
  "period": 30
}
{
  "method_id": "totp-123",
  "issuer": "MyCompany",
  "label": "[email protected]",
  "algorithm": "SHA1",
  "digits": 6,
  "period": 30
}

Delete the configuration for the given TOTP MFA method

delete
Path parameters
method_idstringRequired

The unique identifier for this TOTP MFA method.

Responses
204
Configuration deleted successfully (no content)
delete
DELETE /v1/identity/mfa/method/totp/{method_id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

Read the current configuration for the given ID regardless of the MFA method type

get
Path parameters
method_idstringRequired

The unique identifier for this MFA method.

Responses
200
Successfully retrieved configuration
application/json
Responseany
get
GET /v1/identity/mfa/method/{method_id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "method_id": "totp-456",
  "type": "totp",
  "config": {
    "issuer": "ExampleCorp",
    "label": "[email protected]",
    "digits": 6,
    "period": 30
  }
}

Retrieve public keys

get
Responses
200
Successfully retrieved OIDC public keys
application/json
Responseany
get
GET /v1/identity/oidc/.well-known/keys HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "keys": [
    {
      "kid": "abc123",
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "n": "oahUIzTYT7zK2A1eYAvay89R7hFvKVOw...",
      "e": "AQAB"
    }
  ]
}

Retrieve the OIDC discovery document

get
Responses
200
Successfully retrieved OIDC configuration
application/json
Responseany
get
GET /v1/identity/oidc/.well-known/openid-configuration HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "issuer": "https://example.com/v1/identity/oidc",
  "authorization_endpoint": "https://example.com/v1/identity/oidc/auth",
  "token_endpoint": "https://example.com/v1/identity/oidc/token",
  "userinfo_endpoint": "https://example.com/v1/identity/oidc/userinfo",
  "jwks_uri": "https://example.com/v1/identity/oidc/.well-known/keys",
  "response_types_supported": [
    "code",
    "id_token",
    "token id_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic"
  ],
  "claims_supported": [
    "sub",
    "email",
    "name"
  ]
}

List OIDC assignments

get
Query parameters
liststring · enumRequired

Must be set to true to trigger the listing functionality

Possible values:
Responses
200
Successfully retrieved the list of OIDC assignments
application/json
Responseany
get
GET /v1/identity/oidc/assignment HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "keys": [
    "assignment-role-1",
    "assignment-role-2",
    "assignment-role-3"
  ]
}

Read a specific OIDC assignment

get
Path parameters
namestringRequired

Name of the OIDC assignment

Responses
200
Assignment details retrieved successfully
application/json
Responseany
get
GET /v1/identity/oidc/assignment/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "name": "assignment-role-1",
  "entity_id": "1234-5678",
  "role": "oidc-role-1"
}

Create or update an OIDC assignment

post
Path parameters
namestringRequired

Name of the OIDC assignment

Body
entity_idsstring[]Optional

Comma separated string or array of identity entity IDs

group_idsstring[]Optional

Comma separated string or array of identity group IDs

Responses
200
Assignment created or updated successfully
application/json
Responseany
post
POST /v1/identity/oidc/assignment/{name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 73

{
  "name": "assignment-role-1",
  "entity_id": "1234-5678",
  "role": "oidc-role-1"
}
{
  "success": true,
  "message": "Assignment created successfully."
}

Delete a specific OIDC assignment

delete
Path parameters
namestringRequired

Name of the OIDC assignment

Responses
204
Assignment deleted successfully
delete
DELETE /v1/identity/oidc/assignment/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

List all OIDC clients

get
Query parameters
liststring · enumRequired

Must be set to true

Possible values:
Responses
200
List of clients
application/json
Responseany
get
GET /v1/identity/oidc/client HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "keys": [
    "client-one",
    "client-two"
  ]
}

Read OIDC client configuration

get
Path parameters
namestringRequired

Name of the client.

Responses
200
Client configuration
application/json
Responseany
get
GET /v1/identity/oidc/client/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "client_id": "example-client",
  "redirect_uris": [
    "https://app.example.com/callback"
  ],
  "grant_types": [
    "authorization_code"
  ],
  "response_types": [
    "code"
  ],
  "client_secret": "s3cret"
}

Create or update an OIDC client

post
Path parameters
namestringRequired

Name of the client.

Body
access_token_ttlinteger · secondsOptional

The time-to-live for access tokens obtained by the client.

Default: 24h
assignmentsstring[]Optional

Comma separated string or array of assignment resources.

client_typestringOptional

The client type based on its ability to maintain confidentiality of credentials. The following client types are supported: 'confidential', 'public'. Defaults to 'confidential'.

Default: confidential
id_token_ttlinteger · secondsOptional

The time-to-live for ID tokens obtained by the client.

Default: 24h
keystringOptional

A reference to a named key resource. Cannot be modified after creation. Defaults to the 'default' key.

Default: default
redirect_urisstring[]Optional

Comma separated string or array of redirect URIs used by the client. One of these values must exactly match the redirect_uri parameter value used in each authentication request.

Responses
200
Client created or updated successfully
application/json
Responseany
post
POST /v1/identity/oidc/client/{name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 176

{
  "client_id": "example-client",
  "redirect_uris": [
    "https://app.example.com/callback"
  ],
  "grant_types": [
    "authorization_code"
  ],
  "response_types": [
    "code"
  ],
  "client_secret": "supersecret"
}
{
  "success": true,
  "message": "Client created."
}

Delete an OIDC client

delete
Path parameters
namestringRequired

Name of the client.

Responses
204
Client deleted successfully
delete
DELETE /v1/identity/oidc/client/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

Read OIDC configuration

get
Responses
200
OIDC configuration retrieved successfully
application/json
Responseany
get
GET /v1/identity/oidc/config HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "issuer": "https://auth.example.com",
  "client_id": "example-client",
  "client_secret": "supersecret",
  "scopes_supported": [
    "openid",
    "email"
  ]
}

Create or update OIDC configuration

post
Body
issuerstringOptional

Issuer URL to be used in the iss claim of the token. If not set, Vault's app_addr will be used.

Responses
200
Configuration updated successfully
application/json
Responseany
post
POST /v1/identity/oidc/config HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 134

{
  "issuer": "https://auth.example.com",
  "client_id": "example-client",
  "client_secret": "supersecret",
  "scopes_supported": [
    "openid",
    "email"
  ]
}
{
  "success": true,
  "message": "OIDC configuration updated successfully."
}

Verify the authenticity of an OIDC token

post
Body
client_idstringOptional

Optional client_id to verify

tokenstringOptional

Token to verify

Responses
200
Token introspection successful
application/json
Responseany
post
POST /v1/identity/oidc/introspect HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
{
  "active": true,
  "sub": "1234567890",
  "scope": "openid email",
  "exp": 1713569920,
  "iat": 1713566320,
  "iss": "https://auth.example.com"
}

List OIDC keys

get
Query parameters
liststring · enumRequired

Must be set to true

Example: truePossible values:
Responses
200
OIDC keys listed successfully
application/json
Responseany
get
GET /v1/identity/oidc/key HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "keys": [
    {
      "name": "default",
      "type": "rsa",
      "algorithm": "RS256",
      "creation_time": "2024-01-01T12:00:00Z"
    }
  ]
}

Read OIDC key

get
Path parameters
namestringRequired

Name of the key

Example: default
Responses
200
OIDC key retrieved successfully
application/json
Responseany
get
GET /v1/identity/oidc/key/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "name": "default",
  "type": "rsa",
  "algorithm": "RS256",
  "creation_time": "2024-01-01T12:00:00Z"
}

Create or update OIDC key

post
Path parameters
namestringRequired

Name of the key

Example: default
Body
algorithmstringOptional

Signing algorithm to use. This will default to RS256.

Default: RS256
allowed_client_idsstring[]Optional

Comma separated string or array of role client ids allowed to use this key for signing. If empty no roles are allowed. If "*" all roles are allowed.

rotation_periodinteger · secondsOptional

How often to generate a new keypair.

Default: 24h
verification_ttlinteger · secondsOptional

Controls how long the public portion of a key will be available for verification after being rotated.

Default: 24h
Responses
200
Key created or updated successfully
application/json
Responseany
post
POST /v1/identity/oidc/key/{name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 68

{
  "type": "rsa",
  "algorithm": "RS256",
  "allowed_client_ids": [
    "client-1"
  ]
}
{
  "name": "default",
  "success": true
}

Delete OIDC key

delete
Path parameters
namestringRequired

Name of the key

Example: default
Responses
204
Key deleted successfully (empty body)
delete
DELETE /v1/identity/oidc/key/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

Rotate a named OIDC key.

post
Path parameters
namestringRequired

Name of the key

Example: default-key
Body
verification_ttlinteger · secondsOptional

Controls how long the public portion of a key will be available for verification after being rotated. Setting verification_ttl here will override the verification_ttl set on the key.

Responses
200
Key rotated successfully
application/json
Responseany
post
POST /v1/identity/oidc/key/{name}/rotate HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "key_type": "rsa",
  "algorithm": "RS256"
}
{
  "name": "default-key",
  "rotated": true,
  "creation_time": "2025-04-20T12:00:00Z"
}

List OIDC providers

get
Query parameters
liststring · enumRequired

Must be set to true

Example: truePossible values:
allowed_client_idstringOptional

Filters the list of OIDC providers to those that allow the given client ID in their set of allowed_client_ids.

Default: ""Example: my-client-id
Responses
200
List of OIDC providers retrieved successfully
application/json
Responseany
get
GET /v1/identity/oidc/provider HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "providers": [
    {
      "name": "provider-1",
      "issuer": "https://provider-1.example.com",
      "allowed_client_ids": [
        "my-client-id",
        "admin-client"
      ]
    },
    {
      "name": "provider-2",
      "issuer": "https://provider-2.example.com",
      "allowed_client_ids": [
        "my-client-id"
      ]
    }
  ]
}

Read the OIDC provider configuration

get
Path parameters
namestringRequired

Name of the provider

Example: my-oidc-provider
Responses
200
OIDC provider configuration retrieved successfully
application/json
Responseany
get
GET /v1/identity/oidc/provider/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "name": "my-oidc-provider",
  "issuer": "https://issuer.example.com",
  "client_id": "client-123",
  "client_secret": "secret-value"
}

Create or update an OIDC provider

post
Path parameters
namestringRequired

Name of the provider

Example: my-oidc-provider
Body
allowed_client_idsstring[]Optional

The client IDs that are permitted to use the provider

issuerstringOptional

Specifies what will be used for the iss claim of ID tokens.

scopes_supportedstring[]Optional

The scopes supported for requesting on the provider

Responses
200
Provider successfully created or updated
application/json
Responseany
post
POST /v1/identity/oidc/provider/{name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 144

{
  "issuer": "https://issuer.example.com",
  "client_id": "client-123",
  "client_secret": "secret-value",
  "allowed_client_ids": [
    "client-123",
    "client-abc"
  ]
}
{
  "name": "my-oidc-provider",
  "issuer": "https://issuer.example.com",
  "client_id": "client-123",
  "client_secret": "secret-value"
}

Delete an OIDC provider

delete
Path parameters
namestringRequired

Name of the provider

Example: my-oidc-provider
Responses
204
Provider deleted successfully (no content)
delete
DELETE /v1/identity/oidc/provider/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

Retrieve public keys

get
Path parameters
namestringRequired

Name of the OIDC provider

Example: my-oidc-provider
Responses
200
Successfully retrieved public keys
application/json
Responseany
get
GET /v1/identity/oidc/provider/{name}/.well-known/keys HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "1234abcd",
      "use": "sig",
      "alg": "RS256",
      "n": "0vx7agoebGc...",
      "e": "AQAB"
    }
  ]
}

Query OIDC provider configuration

get
Path parameters
namestringRequired

Name of the OIDC provider

Example: my-oidc-provider
Responses
200
Successfully retrieved the OIDC configuration
application/json
Responseany
get
GET /v1/identity/oidc/provider/{name}/.well-known/openid-configuration HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "issuer": "https://vault.example.com/v1/identity/oidc/provider/my-oidc-provider",
  "authorization_endpoint": "https://vault.example.com/v1/identity/oidc/provider/my-oidc-provider/authorize",
  "token_endpoint": "https://vault.example.com/v1/identity/oidc/provider/my-oidc-provider/token",
  "jwks_uri": "https://vault.example.com/v1/identity/oidc/provider/my-oidc-provider/.well-known/keys",
  "response_types_supported": [
    "code"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

Initiate the OIDC authorization flow using query parameters

get
Path parameters
namestringRequired

Name of the OIDC provider

Example: example-provider
Query parameters
response_typestringRequired

OAuth 2.0 response type

Example: code
client_idstringRequired

Client identifier

Example: my-client-id
redirect_uristringRequired

Callback URI after successful authorization

Example: https://example.com/callback
scopestringOptional

Requested scopes

Example: openid profile email
statestringOptional

Client state to be returned after auth

Example: abc123
Responses
200
Authorization parameters validated successfully
application/json
Responseany
get
GET /v1/identity/oidc/provider/{name}/authorize HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "redirect_to": "https://example.com/consent"
}

Initiate OIDC authorization flow using POST body instead of query params

post
Path parameters
namestringRequired

Name of the OIDC provider

Example: example-provider
Body
client_idstringRequired

The ID of the requesting client.

code_challengestringOptional

The code challenge derived from the code verifier.

code_challenge_methodstringOptional

The method that was used to derive the code challenge. The following methods are supported: 'S256', 'plain'. Defaults to 'plain'.

Default: plain
max_ageintegerOptional

The allowable elapsed time in seconds since the last time the end-user was actively authenticated.

noncestringOptional

The value that will be returned in the ID token nonce claim after a token exchange.

redirect_uristringRequired

The redirection URI to which the response will be sent.

response_typestringRequired

The OIDC authentication flow to be used. The following response types are supported: 'code'

scopestringRequired

A space-delimited, case-sensitive list of scopes to be requested. The 'openid' scope is required.

statestringOptional

The value used to maintain state between the authentication request and client.

Responses
200
Authorization initiated successfully
application/json
Responseany
post
POST /v1/identity/oidc/provider/{name}/authorize HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 145

{
  "response_type": "code",
  "client_id": "my-client-id",
  "redirect_uri": "https://example.com/callback",
  "scope": "openid email profile",
  "state": "xyz789"
}
{
  "redirect_to": "https://example.com/consent"
}

Exchange an authorization code for a token using the OIDC Token endpoint

post
Path parameters
namestringRequired

Name of the provider

Example: example-provider
Body
client_idstringOptional

The ID of the requesting client.

client_secretstringOptional

The secret of the requesting client.

codestringRequired

The authorization code received from the provider's authorization endpoint.

code_verifierstringOptional

The code verifier associated with the authorization code.

grant_typestringRequired

The authorization grant type. The following grant types are supported: 'authorization_code'.

redirect_uristringRequired

The callback location where the authentication response was sent.

Responses
200
Token successfully issued
application/json
Responseany
post
POST /v1/identity/oidc/provider/{name}/token HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 159

{
  "grant_type": "authorization_code",
  "code": "abc123",
  "redirect_uri": "https://example.com/callback",
  "client_id": "my-client-id",
  "client_secret": "my-client-secret"
}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "def456"
}

Retrieve user information from the OIDC provider using the access token

get
Path parameters
namestringRequired

Name of the provider

Example: example-provider
Responses
200
Successfully retrieved user information
application/json
Responseany
get
GET /v1/identity/oidc/provider/{name}/userinfo HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "sub": "1234567890",
  "name": "Jane Doe",
  "email": "[email protected]"
}

Retrieve user information by posting the access token in the request body

post
Path parameters
namestringRequired

Name of the provider

Example: example-provider
Body
anyOptional
Responses
200
Successfully retrieved user information
application/json
Responseany
post
POST /v1/identity/oidc/provider/{name}/userinfo HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 58

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
{
  "sub": "1234567890",
  "name": "Jane Doe",
  "email": "[email protected]"
}

List configured OIDC roles

get
Query parameters
liststring · enumRequired

Must be set to 'true' to list configured roles

Example: truePossible values:
Responses
200
Successfully retrieved list of OIDC roles
application/json
Responseany
get
GET /v1/identity/oidc/role HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "keys": [
    "example-role-1",
    "example-role-2"
  ]
}

Read an OIDC role

get
Path parameters
namestringRequired

Name of the role

Example: developer-role
Responses
200
Successfully retrieved OIDC role configuration
application/json
Responseany
get
GET /v1/identity/oidc/role/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "name": "developer-role",
  "user_claim": "sub",
  "bound_audiences": [
    "my-client"
  ],
  "allowed_redirect_uris": [
    "https://example.com/callback"
  ],
  "ttl": "1h"
}

Create or update an OIDC role

post
Path parameters
namestringRequired

Name of the role

Example: developer-role
Body
client_idstringOptional

Optional client_id

keystringRequired

The OIDC key to use for generating tokens. The specified key must already exist.

templatestringOptional

The template string to use for generating tokens. This may be in string-ified JSON or base64 format.

ttlinteger · secondsOptional

TTL of the tokens generated against the role.

Default: 24h
Responses
200
Successfully created or updated the role
application/json
Responseany
post
POST /v1/identity/oidc/role/{name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 144

{
  "name": "developer-role",
  "user_claim": "sub",
  "bound_audiences": [
    "my-client"
  ],
  "allowed_redirect_uris": [
    "https://example.com/callback"
  ],
  "ttl": "1h"
}
{
  "success": true,
  "data": {
    "name": "developer-role"
  }
}

Delete an OIDC role

delete
Path parameters
namestringRequired

Name of the role

Example: developer-role
Responses
204
Role successfully deleted (no content)
delete
DELETE /v1/identity/oidc/role/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

List configured OIDC scopes

get
Query parameters
liststring · enumRequired

Must be set to 'true' to list configured scopes

Example: truePossible values:
Responses
200
Successfully retrieved list of OIDC scopes
application/json
Responseany
get
GET /v1/identity/oidc/scope HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "keys": [
    "read-only",
    "admin"
  ]
}

Read an OIDC scope

get
Path parameters
namestringRequired

Name of the scope

Example: read-only
Responses
200
Successfully retrieved OIDC scope configuration
application/json
Responseany
get
GET /v1/identity/oidc/scope/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "name": "read-only",
  "description": "Read-only access scope",
  "claims": [
    "sub",
    "email"
  ]
}

Create or update an OIDC scope

post
Path parameters
namestringRequired

Name of the scope

Example: read-only
Body
descriptionstringOptional

The description of the scope

templatestringOptional

The template string to use for the scope. This may be in string-ified JSON or base64 format.

Responses
200
Successfully created or updated the scope
application/json
Responseany
post
POST /v1/identity/oidc/scope/{name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 84

{
  "name": "read-only",
  "description": "Read-only access scope",
  "claims": [
    "sub",
    "email"
  ]
}
{
  "name": "read-only",
  "description": "Read-only access scope",
  "claims": [
    "sub",
    "email"
  ]
}

Delete an OIDC scope

delete
Path parameters
namestringRequired

Name of the scope

Example: read-only
Responses
204
Scope successfully deleted (no content)
delete
DELETE /v1/identity/oidc/scope/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

Generate an OIDC token

get
Path parameters
namestringRequired

Name of the role

Example: developer-role
Responses
200
Successfully generated OIDC token
application/json
Responseany
get
GET /v1/identity/oidc/token/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}

Create a new persona alias.

post
Body
entity_idstringOptional

Entity ID to which this persona belongs to

idstringOptional

ID of the persona

metadataobject · kvpairsOptional

Metadata to be associated with the persona. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: vault metadata=key1=value1 metadata=key2=value2

mount_accessorstringOptional

Mount accessor to which this persona belongs to

namestringOptional

Name of the persona

Responses
200
Successfully created a new alias
application/json
Responseany
post
POST /v1/identity/persona HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "name": "john.doe",
  "metadata": {
    "department": "Engineering",
    "location": "Hyderabad"
  }
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "john.doe",
  "metadata": {
    "department": "Engineering",
    "location": "Hyderabad"
  }
}

List all the alias IDs.

get
Query parameters
liststring · enumRequired

Must be set to 'true' to list all alias IDs

Example: truePossible values:
Responses
200
Successfully retrieved list of alias IDs
application/json
Responseany
get
GET /v1/identity/persona/id HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "987f6543-e21b-34d3-b456-426614174999"
  ]
}

Read an alias by ID

get
Path parameters
idstringRequired

ID of the persona

Example: 123e4567-e89b-12d3-a456-426614174000
Responses
200
Successfully retrieved alias details
application/json
Responseany
get
GET /v1/identity/persona/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "john.doe",
  "metadata": {
    "department": "Engineering",
    "location": "Hyderabad"
  }
}

Update an alias by ID

post
Path parameters
idstringRequired

ID of the persona

Example: 123e4567-e89b-12d3-a456-426614174000
Body
entity_idstringOptional

Entity ID to which this persona should be tied to

metadataobject · kvpairsOptional

Metadata to be associated with the persona. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: vault metadata=key1=value1 metadata=key2=value2

mount_accessorstringOptional

Mount accessor to which this persona belongs to

namestringOptional

Name of the persona

Responses
200
Successfully updated the alias
application/json
Responseany
post
POST /v1/identity/persona/id/{id} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "metadata": {
    "department": "Security",
    "location": "Pune"
  }
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "john.doe",
  "metadata": {
    "department": "Security",
    "location": "Pune"
  }
}

Delete an alias by ID

delete
Path parameters
idstringRequired

ID of the persona

Example: 123e4567-e89b-12d3-a456-426614174000
Responses
204
Successfully deleted. No content returned.
delete
DELETE /v1/identity/persona/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content
PreviousSystemNextModels

Was this helpful?