Identity

PreviousSystem NextModels

Was this helpful?

Read an alias by ID

get

Path parameters

idstringRequired

ID of the alias

Responses

200

Alias details retrieved successfully.

application/json

400

Invalid alias ID or malformed request.

application/json

403

Permission denied to read alias.

application/json

500

Internal server error.

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
}

Delete an alias by ID

delete

Path parameters

idstringRequired

ID of the alias

Responses

204

Alias deleted successfully. No content is returned.

400

Invalid alias ID.

application/json

403

Not authorized to delete alias.

application/json

500

Internal error during deletion.

application/json

delete

DELETE /v1/identity/alias/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

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

400

Bad request – missing or incorrect query param.

application/json

403

Insufficient permissions to list aliases.

application/json

500

Internal server error.

application/json

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

400

Invalid alias ID

application/json

403

Permission denied

application/json

500

Internal server error

application/json

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"
    }
  }
}

Delete an alias by ID for the entity

delete

Path parameters

idstringRequired

ID of the alias

Responses

204

Alias deleted successfully. No content returned.

400

Invalid alias ID

application/json

403

Unauthorized to delete alias

application/json

500

Server error

application/json

delete

DELETE /v1/identity/entity-alias/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

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

400

Invalid or missing query parameter.

application/json

403

Access denied due to insufficient permissions.

application/json

500

Server encountered an unexpected condition.

application/json

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

400

Invalid request.

application/json

403

Forbidden. You don’t have permission to perform this action.

application/json

500

Internal server error.

application/json

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"
    }
  }
}

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.

400

Invalid entity ID.

application/json

403

Access denied.

application/json

500

Server error during deletion.

application/json

delete

DELETE /v1/identity/entity/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

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

400

Bad request due to missing or invalid query parameter.

application/json

403

Forbidden. The user does not have permission to access this resource.

application/json

500

Internal server error occurred while processing the request.

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

400

Bad request due to invalid input.

application/json

403

Forbidden. Access denied.

application/json

500

Internal server error.

application/json

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"
    ]
  }
}

Delete an entity by name

delete

Path parameters

namestringRequired

Name of the entity

Responses

204

Entity deleted successfully. No content returned.

400

Bad request.

application/json

403

Forbidden.

application/json

500

Internal error.

application/json

delete

DELETE /v1/identity/entity/name/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

List all the group alias IDs

get

Query parameters

liststring · enumRequired

Must be set to true

Example: truePossible values:

Responses

200

application/json

Responseany

400

Bad Request - The request is malformed or invalid.

application/json

403

Forbidden - The user does not have permission to access the resource.

application/json

500

Internal Server Error - An error occurred on the server.

application/json

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

application/json

Responseany

400

Bad Request - Invalid alias ID.

application/json

403

Forbidden - Access to the alias is not allowed.

application/json

500

Internal Server Error

application/json

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."
}

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.

400

Bad Request - Invalid alias ID format.

application/json

403

Forbidden - Insufficient permissions to delete the alias.

application/json

500

Internal Server Error

application/json

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

400

Bad Request - Missing or invalid query parameter.

application/json

403

Forbidden - You are not authorized to list group IDs.

application/json

500

Internal Server Error - Unexpected failure while retrieving groups.

application/json

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

400

Bad Request - Invalid ID format.

application/json

403

Forbidden - Access denied to group.

application/json

500

Internal Server Error

application/json

get

GET /v1/identity/group/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "id": "group123",
  "name": "Admins",
  "description": "Administrators 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.

400

Bad Request - Invalid group ID.

application/json

403

Forbidden - Not authorized to delete group.

application/json

500

Internal Server Error

application/json

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

400

Bad Request - Missing or invalid query parameter.

application/json

403

Forbidden - Access denied to list group names.

application/json

500

Internal Server Error - Unexpected failure.

application/json

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

400

Bad Request - Invalid group name.

application/json

403

Forbidden - You are not authorized to access this group.

application/json

500

Internal Server Error - Failed to retrieve group.

application/json

get

GET /v1/identity/group/name/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "name": "Admins",
  "id": "group123",
  "description": "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.

400

Bad Request - Invalid group name.

application/json

403

Forbidden - You are not authorized to delete this group.

application/json

500

Internal Server Error - Failed to delete group.

application/json

delete

DELETE /v1/identity/group/name/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

get

Query parameters

liststring · enumRequired

Must be set to true

Example: truePossible values:

Responses

200

MFA login enforcements retrieved successfully.

application/json

Responseany

400

Bad Request - Invalid query parameters.

application/json

403

Forbidden - You are not authorized to view this information.

application/json

500

Internal Server Error - Unable to retrieve enforcement list.

application/json

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
    }
  ]
}

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

application/json

Responseany

400

Bad Request - Invalid rule name.

application/json

403

Forbidden - Not authorized to access the rule.

application/json

500

Internal Server Error

application/json

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
}

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

400

Bad Request - Invalid rule name.

application/json

403

Forbidden - You are not authorized to delete this rule.

application/json

500

Internal Server Error - Failed to delete rule.

application/json

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

400

Bad Request – The query parameter is missing or invalid.

application/json

403

Forbidden – The client does not have access rights to the content.

application/json

500

Internal Server Error – Something went wrong on the server.

application/json

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

400

Bad Request – Missing or incorrect query parameter.

application/json

403

Forbidden – Access denied to Duo configuration.

application/json

500

Internal Server Error – Failed to fetch Duo configuration.

application/json

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

400

Bad Request – Invalid method ID format.

application/json

403

Forbidden – Access denied to this configuration.

application/json

500

Internal Server Error

application/json

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.

400

Bad Request – Invalid method ID format.

application/json

403

Forbidden – Insufficient permissions.

application/json

500

Internal Server Error

application/json

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[]

400

Bad Request – Invalid query parameter.

application/json

403

Forbidden – Insufficient permissions.

application/json

500

Internal Server Error – Something went wrong.

application/json

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

400

Invalid method_id provided

application/json

403

Forbidden – You don’t have permission

application/json

500

Internal Server Error

application/json

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"
}

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

400

Invalid method_id

application/json

403

Forbidden – You do not have permission

application/json

500

Internal Server Error

application/json

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

400

Invalid request parameter

application/json

500

Internal server error

application/json

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

404

Configuration not found

application/json

500

Server error

application/json

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"
}

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

500

Failed to delete configuration

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[]

400

Invalid query parameter

application/json

500

Internal server error

application/json

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
  }
]

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

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Configuration not found

application/json

500

Internal server error

application/json

get

GET /v1/identity/mfa/method/totp/{method_id} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "method_id": "totp-123",
  "issuer": "MyCompany",
  "label": "user@example.com",
  "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)

401

Unauthorized

application/json

403

Forbidden

application/json

404

Configuration not found

application/json

500

Internal server error

application/json

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

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Configuration not found

application/json

500

Internal server error

application/json

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": "admin@example.com",
    "digits": 6,
    "period": 30
  }
}

Retrieve public keys

get

Responses

200

Successfully retrieved OIDC public keys

application/json

Responseany

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal server error

application/json

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

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal server error

application/json

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

400

Bad request due to missing or invalid parameters

application/json

401

Unauthorized access

application/json

403

Forbidden due to insufficient permissions

application/json

500

Internal server error

application/json

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

400

Invalid assignment name

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Assignment not found

application/json

500

Server error

application/json

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"
}

Delete a specific OIDC assignment

delete

Path parameters

namestringRequired

Name of the OIDC assignment

Responses

204

Assignment deleted successfully

400

Invalid assignment name

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Assignment not found

application/json

500

Internal server error

application/json

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

400

Bad request

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

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

401

Unauthorized

application/json

403

Forbidden

application/json

404

Client not found

application/json

500

Internal server error

application/json

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"
}

Delete an OIDC client

delete

Path parameters

namestringRequired

Name of the client.

Responses

204

Client deleted successfully

401

Unauthorized

application/json

403

Forbidden

application/json

404

Client not found

application/json

500

Internal server error

application/json

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

401

Unauthorized

application/json

403

Forbidden

application/json

404

Configuration not found

application/json

500

Internal server error

application/json

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"
  ]
}

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

400

Invalid query parameter

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal server error

application/json

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

400

Invalid key name

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Key not found

application/json

500

Internal server error

application/json

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"
}

Delete OIDC key

delete

Path parameters

namestringRequired

Name of the key

Example: default

Responses

204

Key deleted successfully (empty body)

400

Invalid key name

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Key not found

application/json

500

Internal server error

application/json

delete

DELETE /v1/identity/oidc/key/{name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

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

400

Invalid query parameters

application/json

401

Unauthorized request

application/json

403

Access forbidden

application/json

404

Resource not found

application/json

500

Internal server error

application/json

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

400

Bad request

application/json

401

Unauthorized access

application/json

403

Access forbidden

application/json

404

Provider not found

application/json

500

Internal server error

application/json

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"
}

Delete an OIDC provider

delete

Path parameters

namestringRequired

Name of the provider

Example: my-oidc-provider

Responses

204

Provider deleted successfully (no content)

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Provider not found

application/json

500

Internal server error

application/json

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

400

Bad request (e.g., missing or malformed provider name)

application/json

401

Unauthorized (if incorrectly marked unauthenticated)

application/json

403

Forbidden (access denied)

application/json

404

Provider not found

application/json

500

Internal server error

application/json

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

400

Invalid request or malformed provider name

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Provider not found

application/json

500

Internal server error

application/json

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

400

Bad request or missing parameters

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

OIDC provider not found

application/json

500

Internal server error

application/json

get

GET /v1/identity/oidc/provider/{name}/authorize HTTP/1.1
Host: localhost:8200
Accept: */*

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

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

400

Invalid request

application/json

401

Unauthorized – Invalid or expired token

application/json

403

Forbidden – Access denied

application/json

404

OIDC provider not found

application/json

500

Internal server error

application/json

get

GET /v1/identity/oidc/provider/{name}/userinfo HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "sub": "1234567890",
  "name": "Jane Doe",
  "email": "jane.doe@example.com"
}

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

400

Invalid request parameter

application/json

401

Unauthorized – missing or invalid token

application/json

500

Internal server error

application/json

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

400

Invalid request format

application/json

401

Unauthorized

application/json

404

Role not found

application/json

500

Internal server error

application/json

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"
}

Delete an OIDC role

delete

Path parameters

namestringRequired

Name of the role

Example: developer-role

Responses

204

Role successfully deleted (no content)

400

Invalid role name

application/json

401

Unauthorized

application/json

404

Role not found

application/json

500

Internal server error

application/json

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

400

Invalid request parameter

application/json

401

Unauthorized – missing or invalid token

application/json

500

Internal server error

application/json

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

400

Invalid request format

application/json

401

Unauthorized

application/json

404

Scope not found

application/json

500

Internal server error

application/json

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"
  ]
}

Delete an OIDC scope

delete

Path parameters

namestringRequired

Name of the scope

Example: read-only

Responses

204

Scope successfully deleted (no content)

400

Invalid scope name

application/json

401

Unauthorized

application/json

404

Scope not found

application/json

500

Internal server error

application/json

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

400

Invalid request parameters

application/json

401

Unauthorized – missing or invalid token

application/json

404

Role not found

application/json

500

Internal server error

application/json

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"
}

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

400

Invalid request parameter

application/json

401

Unauthorized – missing or invalid token

application/json

500

Internal server error

application/json

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

400

Invalid ID format

application/json

401

Unauthorized – missing or invalid credentials

application/json

404

Persona ID not found

application/json

500

Internal server error

application/json

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"
  }
}

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.

400

Invalid ID format

application/json

401

Unauthorized – authentication required

application/json

404

Persona ID not found

application/json

500

Server error

application/json

delete

DELETE /v1/identity/persona/id/{id} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

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

400

Bad request – missing or incorrect query param.

application/json

500

Internal server error.

application/json

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
}

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

400

Invalid request payload.

application/json

403

Insufficient permissions to create alias.

application/json

500

Internal server error.

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"
    }
  }
}

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

400

Malformed request or missing fields.

application/json

403

Not authorized to update alias.

application/json

500

Internal server error during update.

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"
    }
  }
}

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

400

Invalid request payload.

application/json

403

Insufficient permissions to create entity.

application/json

500

Internal server error.

application/json

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

400

Invalid request payload.

application/json

403

Insufficient permissions to create alias.

application/json

500

Internal server error.

application/json

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"
    }
  }
}

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

400

Invalid request payload

application/json

403

Unauthorized to update alias

application/json

500

Server error

application/json

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 all of the entities

post

Body

entity_idsstring[]Optional

Entity IDs to delete

Responses

200

Entities deleted successfully.

application/json

Responseany

400

Bad request due to invalid input.

application/json

403

Permission denied.

application/json

500

Server error.

application/json

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": []
}

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

400

Invalid request body.

application/json

403

Unauthorized request.

application/json

500

Internal server error.

application/json

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"
    }
  }
}

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

400

Invalid merge request.

application/json

403

Access denied.

application/json

500

Internal server error.

application/json

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"
    }
  }
}

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

400

Invalid request data.

application/json

403

Unauthorized request.

application/json

500

Server error occurred.

application/json

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"
    ]
  }
}

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

400

Bad request due to missing or invalid fields.

application/json

403

Forbidden. You do not have permission to create a group.

application/json

500

Internal server error.

application/json

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

400

Bad request due to missing or invalid fields.

application/json

403

Forbidden. You do not have permission to create or update a group alias.

application/json

500

Internal server error.

application/json

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"
    }
  }
}

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

application/json

Responseany

400

Bad Request - Invalid input data.

application/json

403

Forbidden - User lacks permission to update alias.

application/json

500

Internal Server Error

application/json

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."
}

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

400

Bad Request - Invalid input data.

application/json

403

Forbidden - Not authorized to update group.

application/json

500

Internal Server Error

application/json

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"
}

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

400

Bad Request - Invalid input.

application/json

403

Forbidden - You are not authorized to update this group.

application/json

500

Internal Server Error - Failed to update group.

application/json

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"
}

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

400

Bad Request - Invalid input format.

application/json

403

Forbidden - You do not have permission to perform this lookup.

application/json

500

Internal Server Error - Unexpected failure during lookup.

application/json

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

400

Bad Request - Invalid or missing lookup parameter.

application/json

403

Forbidden - You are not authorized to perform this operation.

application/json

500

Internal Server Error - Lookup operation failed.

application/json

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"
    }
  ]
}

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

application/json

Responseany

400

Bad Request - Invalid request body.

application/json

403

Forbidden - You do not have permission to modify this rule.

application/json

500

Internal Server Error - Failure during write.

application/json

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
}

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

400

Invalid input

application/json

403

Unauthorized to update method

application/json

500

Configuration error

application/json

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"
}

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

400

Invalid input

application/json

500

Internal server error

application/json

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 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

400

Invalid request parameters

application/json

404

Entity or secret not found

application/json

500

Internal server error

application/json

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

400

Invalid request payload

application/json

404

Entity not found

application/json

500

Internal server error

application/json

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:user@example.com?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

400

Invalid request

application/json

404

Entity not found

application/json

500

Internal server error

application/json

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:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example"
}

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

400

Invalid request body

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal server error

application/json

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": "user@example.com",
  "algorithm": "SHA1",
  "digits": 6,
  "period": 30
}

{
  "method_id": "totp-123",
  "issuer": "MyCompany",
  "label": "user@example.com",
  "algorithm": "SHA1",
  "digits": 6,
  "period": 30
}

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

400

Bad request due to missing or invalid fields

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal server error

application/json

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."
}

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

400

Validation error

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal server error

application/json

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."
}

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

400

Invalid input

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal server error

application/json

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

400

Invalid request body

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal server error

application/json

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"
}

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

400

Invalid input

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal server error

application/json

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
}

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

400

Invalid request data

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Key not found

application/json

500

Internal server error

application/json

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"
}

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

400

Validation error

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal server error

application/json

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"
}

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

400

Invalid request body or missing fields

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

OIDC provider not found

application/json

500

Server error during authorization

application/json

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

400

Invalid request, missing or malformed parameters

application/json

401

Unauthorized – Invalid client credentials

application/json

403

Forbidden – Client not allowed to obtain token

application/json

404

Provider not found

application/json

500

Internal server error

application/json

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 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

400

Invalid request

application/json

401

Unauthorized – Invalid or expired token

application/json

403

Forbidden – Access denied

application/json

404

OIDC provider not found

application/json

500

Internal server error

application/json

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": "jane.doe@example.com"
}

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

400

Validation error

application/json

401

Unauthorized

application/json

500

Server error

application/json

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"
  }
}

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

400

Validation error

application/json

401

Unauthorized

application/json

500

Server error

application/json

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"
  ]
}

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

400

Invalid request body

application/json

401

Unauthorized – missing or invalid token

application/json

500

Internal server error

application/json

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"
  }
}

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

400

Invalid update payload

application/json

401

Unauthorized – authentication required

application/json

404

Persona ID not found

application/json

500

Internal server error

application/json

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"
  }
}

Read an alias by ID

Delete an alias by ID

List all the alias IDs for the entity

Read an alias by ID for the entity

Delete an alias by ID for the entity

List all the entity IDs

Read an entity by ID

Delete an entity by ID

List all the entity names

Read an entity by name

Delete an entity by name

List all the group alias IDs

Read a group alias by its ID

Delete a group alias by its ID

List all the group IDs

Read group details by ID

Delete a group by ID

List all group names

Read a group by its name

Delete a group by its name

List login enforcement rules

Read a login enforcement configuration

Delete a login enforcement configuration

List MFA method configurations for all MFA methods

List Duo MFA method configurations

Read the current configuration for the given MFA method

Delete a configuration for the given MFA method

List MFA method configurations for the given MFA method

Read the current configuration for the given MFA method

Delete a configuration for the given MFA method

List MFA method configurations for PingID

Read the current configuration for the given PingID MFA method

Delete a configuration for the given PingID MFA method

List MFA method configurations for the TOTP method

Read the current configuration for the given TOTP MFA method

Delete the configuration for the given TOTP MFA method

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

Retrieve public keys

Retrieve the OIDC discovery document

List OIDC assignments

Read a specific OIDC assignment

Delete a specific OIDC assignment

List all OIDC clients

Read OIDC client configuration

Delete an OIDC client

Read OIDC configuration

List OIDC keys

Read OIDC key

Delete OIDC key

List OIDC providers

Read the OIDC provider configuration

Delete an OIDC provider

Retrieve public keys

Query OIDC provider configuration

Initiate the OIDC authorization flow using query parameters

Retrieve user information from the OIDC provider using the access token

List configured OIDC roles

Read an OIDC role

Delete an OIDC role

List configured OIDC scopes

Read an OIDC scope

Delete an OIDC scope

Generate an OIDC token

List all the alias IDs.

Read an alias by ID

Delete an alias by ID

List all the alias IDs

Create a new alias.

Update an alias by ID

Create a new entity

Create a new alias for the entity

Update an alias by ID for the entity

Delete all of the entities

Update an entity by ID

Merge two or more entities together

Update an entity by name

Create a new group

Create a new group alias, or update an existing one

Update a group alias by its ID

Update an existing group by ID