openapi: 3.1.0 info: title: HashiCorp Vault Vault Identity API description: >- APIs for managing identity entities, entity aliases, groups, and group aliases in HashiCorp Vault. The identity system provides a unified view of users and machines across all authentication methods. version: '1.0' contact: name: HashiCorp Support email: support@hashicorp.com url: https://support.hashicorp.com/ license: name: Business Source License 1.1 url: https://github.com/hashicorp/vault/blob/main/LICENSE externalDocs: description: Vault Identity API Documentation url: https://developer.hashicorp.com/vault/api-docs/secret/identity servers: - url: https://vault.example.com/v1 description: Vault Server tags: - name: Entity description: Identity entity management - name: Entity Alias description: Identity entity alias management - name: Group description: Identity group management - name: Group Alias description: Identity group alias management - name: Lookup description: Identity lookup operations - name: OIDC description: OIDC identity provider operations security: - vaultToken: [] paths: /identity/entity: post: operationId: createEntity summary: HashiCorp Vault Create entity description: Creates or updates an identity entity. tags: - Entity requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EntityRequest' responses: '200': description: Entity created or updated content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Entity' '400': description: Invalid request '403': description: Permission denied get: operationId: listEntities summary: HashiCorp Vault List entities description: Lists all identity entities by ID. tags: - Entity responses: '200': description: Entities listed content: application/json: schema: type: object properties: data: type: object properties: keys: type: array items: type: string description: List of entity IDs key_info: type: object additionalProperties: type: object properties: name: type: string aliases: type: array items: type: object '403': description: Permission denied /identity/entity/id/{id}: get: operationId: readEntityById summary: HashiCorp Vault Read entity by ID description: Reads the identity entity with the given ID. tags: - Entity parameters: - $ref: '#/components/parameters/entityId' responses: '200': description: Entity returned content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Entity' '403': description: Permission denied '404': description: Entity not found post: operationId: updateEntityById summary: HashiCorp Vault Update entity by ID description: Updates the identity entity with the given ID. tags: - Entity parameters: - $ref: '#/components/parameters/entityId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EntityRequest' responses: '200': description: Entity updated content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Entity' '400': description: Invalid request '403': description: Permission denied delete: operationId: deleteEntityById summary: HashiCorp Vault Delete entity by ID description: Deletes the identity entity with the given ID. tags: - Entity parameters: - $ref: '#/components/parameters/entityId' responses: '204': description: Entity deleted '403': description: Permission denied /identity/entity/name/{name}: get: operationId: readEntityByName summary: HashiCorp Vault Read entity by name description: Reads the identity entity with the given name. tags: - Entity parameters: - name: name in: path required: true description: Name of the entity schema: type: string responses: '200': description: Entity returned content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Entity' '404': description: Entity not found post: operationId: updateEntityByName summary: HashiCorp Vault Update entity by name description: Updates the identity entity with the given name. tags: - Entity parameters: - name: name in: path required: true description: Name of the entity schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EntityRequest' responses: '200': description: Entity updated content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Entity' '400': description: Invalid request delete: operationId: deleteEntityByName summary: HashiCorp Vault Delete entity by name description: Deletes the identity entity with the given name. tags: - Entity parameters: - name: name in: path required: true description: Name of the entity schema: type: string responses: '204': description: Entity deleted /identity/entity/batch-delete: post: operationId: batchDeleteEntities summary: HashiCorp Vault Batch delete entities description: Deletes multiple identity entities by their IDs. tags: - Entity requestBody: required: true content: application/json: schema: type: object required: - entity_ids properties: entity_ids: type: array items: type: string description: List of entity IDs to delete responses: '204': description: Entities deleted '403': description: Permission denied /identity/entity/merge: post: operationId: mergeEntities summary: HashiCorp Vault Merge entities description: >- Merges two or more entities into a single entity. Aliases from the source entities are transferred to the destination entity. tags: - Entity requestBody: required: true content: application/json: schema: type: object required: - from_entity_ids - to_entity_id properties: from_entity_ids: type: array items: type: string description: Entity IDs to merge from to_entity_id: type: string description: Entity ID to merge into force: type: boolean description: Force merge even if there are conflicting aliases responses: '204': description: Entities merged '400': description: Invalid request '403': description: Permission denied /identity/entity-alias: post: operationId: createEntityAlias summary: HashiCorp Vault Create entity alias description: >- Creates an entity alias that maps an authentication method's identity to a Vault entity. tags: - Entity Alias requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EntityAliasRequest' responses: '200': description: Entity alias created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/EntityAlias' '400': description: Invalid request '403': description: Permission denied /identity/entity-alias/id/{id}: get: operationId: readEntityAlias summary: HashiCorp Vault Read entity alias description: Reads the entity alias with the given ID. tags: - Entity Alias parameters: - name: id in: path required: true description: Entity alias ID schema: type: string responses: '200': description: Entity alias returned content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/EntityAlias' '404': description: Entity alias not found post: operationId: updateEntityAlias summary: HashiCorp Vault Update entity alias description: Updates the entity alias with the given ID. tags: - Entity Alias parameters: - name: id in: path required: true description: Entity alias ID schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EntityAliasRequest' responses: '200': description: Entity alias updated '400': description: Invalid request delete: operationId: deleteEntityAlias summary: HashiCorp Vault Delete entity alias description: Deletes the entity alias with the given ID. tags: - Entity Alias parameters: - name: id in: path required: true description: Entity alias ID schema: type: string responses: '204': description: Entity alias deleted /identity/group: post: operationId: createGroup summary: HashiCorp Vault Create group description: Creates or updates an identity group. tags: - Group requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GroupRequest' responses: '200': description: Group created or updated content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Group' '400': description: Invalid request '403': description: Permission denied get: operationId: listGroups summary: HashiCorp Vault List groups description: Lists all identity groups by ID. tags: - Group responses: '200': description: Groups listed content: application/json: schema: type: object properties: data: type: object properties: keys: type: array items: type: string description: List of group IDs '403': description: Permission denied /identity/group/id/{id}: get: operationId: readGroupById summary: HashiCorp Vault Read group by ID description: Reads the identity group with the given ID. tags: - Group parameters: - name: id in: path required: true description: Group ID schema: type: string responses: '200': description: Group returned content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Group' '404': description: Group not found post: operationId: updateGroupById summary: HashiCorp Vault Update group by ID description: Updates the identity group with the given ID. tags: - Group parameters: - name: id in: path required: true description: Group ID schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GroupRequest' responses: '200': description: Group updated '400': description: Invalid request delete: operationId: deleteGroupById summary: HashiCorp Vault Delete group by ID description: Deletes the identity group with the given ID. tags: - Group parameters: - name: id in: path required: true description: Group ID schema: type: string responses: '204': description: Group deleted /identity/group/name/{name}: get: operationId: readGroupByName summary: HashiCorp Vault Read group by name description: Reads the identity group with the given name. tags: - Group parameters: - name: name in: path required: true description: Name of the group schema: type: string responses: '200': description: Group returned content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Group' '404': description: Group not found post: operationId: updateGroupByName summary: HashiCorp Vault Update group by name description: Updates the identity group with the given name. tags: - Group parameters: - name: name in: path required: true description: Name of the group schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GroupRequest' responses: '200': description: Group updated '400': description: Invalid request delete: operationId: deleteGroupByName summary: HashiCorp Vault Delete group by name description: Deletes the identity group with the given name. tags: - Group parameters: - name: name in: path required: true description: Name of the group schema: type: string responses: '204': description: Group deleted /identity/group-alias: post: operationId: createGroupAlias summary: HashiCorp Vault Create group alias description: >- Creates a group alias that maps an external group from an auth method to a Vault identity group. tags: - Group Alias requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GroupAliasRequest' responses: '200': description: Group alias created content: application/json: schema: type: object properties: data: type: object properties: id: type: string description: Group alias ID canonical_id: type: string description: Group ID '400': description: Invalid request '403': description: Permission denied /identity/group-alias/id/{id}: get: operationId: readGroupAlias summary: HashiCorp Vault Read group alias description: Reads the group alias with the given ID. tags: - Group Alias parameters: - name: id in: path required: true description: Group alias ID schema: type: string responses: '200': description: Group alias returned content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/GroupAlias' '404': description: Group alias not found post: operationId: updateGroupAlias summary: HashiCorp Vault Update group alias description: Updates the group alias with the given ID. tags: - Group Alias parameters: - name: id in: path required: true description: Group alias ID schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GroupAliasRequest' responses: '200': description: Group alias updated '400': description: Invalid request delete: operationId: deleteGroupAlias summary: HashiCorp Vault Delete group alias description: Deletes the group alias with the given ID. tags: - Group Alias parameters: - name: id in: path required: true description: Group alias ID schema: type: string responses: '204': description: Group alias deleted /identity/lookup/entity: post: operationId: lookupEntity summary: HashiCorp Vault Lookup entity description: >- Looks up an entity by any of its identifying attributes such as name, ID, or alias details. tags: - Lookup requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: Entity name to look up id: type: string description: Entity ID to look up alias_id: type: string description: Alias ID to look up alias_name: type: string description: Alias name to look up alias_mount_accessor: type: string description: Auth mount accessor for alias lookup responses: '200': description: Entity found content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Entity' '204': description: Entity not found '400': description: Invalid request /identity/lookup/group: post: operationId: lookupGroup summary: HashiCorp Vault Lookup group description: >- Looks up a group by any of its identifying attributes such as name, ID, or alias details. tags: - Lookup requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: Group name to look up id: type: string description: Group ID to look up alias_id: type: string description: Alias ID to look up alias_name: type: string description: Alias name to look up alias_mount_accessor: type: string description: Auth mount accessor for alias lookup responses: '200': description: Group found content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Group' '204': description: Group not found '400': description: Invalid request /identity/oidc/token/{name}: get: operationId: readOidcToken summary: HashiCorp Vault Read OIDC token description: >- Generates an OIDC identity token for the requesting entity based on the named role. tags: - OIDC parameters: - name: name in: path required: true description: Name of the OIDC role schema: type: string responses: '200': description: OIDC token generated content: application/json: schema: type: object properties: data: type: object properties: token: type: string description: Signed OIDC identity token client_id: type: string description: Client ID for the OIDC role ttl: type: integer description: Token TTL in seconds '403': description: Permission denied /identity/oidc/.well-known/openid-configuration: get: operationId: readOidcWellKnownConfig summary: HashiCorp Vault Read OIDC discovery configuration description: >- Returns the OIDC discovery document for Vault's identity OIDC provider. tags: - OIDC responses: '200': description: OIDC discovery configuration content: application/json: schema: type: object properties: issuer: type: string description: OIDC issuer URL jwks_uri: type: string description: URL for the JWKS endpoint authorization_endpoint: type: string token_endpoint: type: string id_token_signing_alg_values_supported: type: array items: type: string subject_types_supported: type: array items: type: string response_types_supported: type: array items: type: string scopes_supported: type: array items: type: string security: [] /identity/oidc/.well-known/keys: get: operationId: readOidcJwks summary: HashiCorp Vault Read OIDC JWKS description: Returns the public keys used to verify OIDC identity tokens. tags: - OIDC responses: '200': description: JWKS returned content: application/json: schema: type: object properties: keys: type: array items: type: object properties: kty: type: string kid: type: string use: type: string n: type: string e: type: string alg: type: string security: [] components: securitySchemes: vaultToken: type: apiKey in: header name: X-Vault-Token description: Vault authentication token parameters: entityId: name: id in: path required: true description: Entity unique identifier schema: type: string schemas: Entity: type: object properties: id: type: string description: Unique identifier for the entity name: type: string description: Name of the entity metadata: type: object additionalProperties: type: string description: Metadata key-value pairs disabled: type: boolean description: Whether the entity is disabled aliases: type: array items: $ref: '#/components/schemas/EntityAlias' description: Entity aliases direct_group_ids: type: array items: type: string description: IDs of groups the entity directly belongs to inherited_group_ids: type: array items: type: string description: IDs of groups inherited through group hierarchy policies: type: array items: type: string description: Policies directly assigned to the entity creation_time: type: string format: date-time description: Entity creation time last_update_time: type: string format: date-time description: Last update time EntityRequest: type: object properties: name: type: string description: Name of the entity metadata: type: object additionalProperties: type: string description: Metadata key-value pairs policies: type: array items: type: string description: Policies to assign to the entity disabled: type: boolean description: Whether the entity is disabled EntityAlias: type: object properties: id: type: string description: Unique identifier for the alias canonical_id: type: string description: Entity ID this alias belongs to mount_accessor: type: string description: Auth mount accessor mount_path: type: string description: Auth mount path mount_type: type: string description: Auth mount type name: type: string description: Name of the alias (auth-method-specific identifier) metadata: type: object additionalProperties: type: string description: Metadata from the auth method creation_time: type: string format: date-time last_update_time: type: string format: date-time EntityAliasRequest: type: object required: - name - mount_accessor - canonical_id properties: name: type: string description: Name of the alias mount_accessor: type: string description: Auth mount accessor canonical_id: type: string description: Entity ID to associate with custom_metadata: type: object additionalProperties: type: string description: Custom metadata Group: type: object properties: id: type: string description: Unique identifier for the group name: type: string description: Name of the group type: type: string enum: - internal - external description: Group type metadata: type: object additionalProperties: type: string description: Metadata key-value pairs policies: type: array items: type: string description: Policies assigned to the group member_entity_ids: type: array items: type: string description: Entity IDs that are members of this group member_group_ids: type: array items: type: string description: Group IDs that are members of this group parent_group_ids: type: array items: type: string description: Parent group IDs alias: $ref: '#/components/schemas/GroupAlias' creation_time: type: string format: date-time last_update_time: type: string format: date-time GroupRequest: type: object properties: name: type: string description: Name of the group type: type: string enum: - internal - external description: Group type (cannot be changed after creation) metadata: type: object additionalProperties: type: string description: Metadata key-value pairs policies: type: array items: type: string description: Policies to assign to the group member_entity_ids: type: array items: type: string description: Entity IDs to add as members member_group_ids: type: array items: type: string description: Group IDs to add as members GroupAlias: type: object properties: id: type: string description: Unique identifier for the alias canonical_id: type: string description: Group ID this alias belongs to mount_accessor: type: string description: Auth mount accessor mount_path: type: string description: Auth mount path mount_type: type: string description: Auth mount type name: type: string description: Name of the alias (external group name) creation_time: type: string format: date-time last_update_time: type: string format: date-time GroupAliasRequest: type: object required: - name - mount_accessor - canonical_id properties: name: type: string description: Name of the alias (external group identifier) mount_accessor: type: string description: Auth mount accessor canonical_id: type: string description: Group ID to associate with