Key Managers¶

Create a key manager¶

POST /key-managers

Code samples

curl -X POST https://localhost:9543/api/v0.9/key-managers \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Creates a key manager configuration for the organization. If id is omitted, the service generates one from the display name. Accepts either a application/json body or a multipart/form-data upload with a keymanager field containing the KeyManager YAML file. OAuth applications are created directly in the key manager itself, outside the portal — the portal only needs the token endpoint to proxy client_appKeyMappings token requests.

Payload

{
  "displayName": "Asgardeo",
  "id": "asgardeo-prod",
  "enabled": true,
  "tokenEndpoint": "https://api.asgardeo.io/t/myorg/oauth2/token"
}

displayName: Asgardeo
id: asgardeo-prod
enabled: true
tokenEndpoint: https://api.asgardeo.io/t/myorg/oauth2/token

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	KeyManagerRequest	false	Key manager configuration payload. Submit as `application/json` or as `multipart/form-data` with a `keymanager` field containing a KeyManager YAML file.

Example responses

201 Response

{
  "id": "asgardeo-prod",
  "displayName": "Asgardeo",
  "orgId": "org-12345",
  "enabled": true,
  "tokenEndpoint": "https://api.asgardeo.io/t/myorg/oauth2/token",
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
201	Created	Key manager configuration response.	KeyManagerResponseSchema
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Response Headers¶

Status	Header	Type	Format	Description
201	Location	string	uri	URL of the created key manager.

List key managers¶

GET /key-managers

Code samples

curl -X GET https://localhost:9543/api/v0.9/key-managers \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Returns key manager configurations for the organization. Admins receive the full configuration for every key manager, including disabled ones; other callers receive the minimal, developer-facing view of enabled key managers only, with no admin credentials. Admin appKeyMappings are never included in the response.

Authentication¶

Parameters

Name	In	Type	Required	Description
limit	query	integer	false	Maximum number of records to return.
offset	query	integer	false	Number of records to skip before returning results.

Example responses

200 Response

{
  "list": [
    {
      "id": "asgardeo-prod",
      "displayName": "Asgardeo",
      "orgId": "org-12345",
      "enabled": true,
      "tokenEndpoint": "https://api.asgardeo.io/t/myorg/oauth2/token",
      "createdBy": "[email protected]",
      "createdAt": "2026-05-07T08:30:00Z",
      "updatedAt": "2026-05-07T08:30:00Z"
    }
  ],
  "count": 1,
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	List of key manager configurations. Admins receive KeyManagerResponseSchema items; other callers receive the minimal KeyManagerPublicResponseSchema items.	Inline
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» list	[anyOf]	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
»» anonymous	KeyManagerResponseSchema	false	none	Key manager configuration.
»»» id	string	false	none	The key manager's handle (unique per org). Not the internal database uuid.
»»» displayName	string	false	none	none
»»» orgId	string	false	none	none
»»» enabled	boolean	false	none	none
»»» tokenEndpoint	string(uri)	false	none	none
»»» createdBy	string	false	none	Identity of the user who created this key manager, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses and list items.
»»» updatedBy	string	false	none	Identity of the user who last updated this key manager, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses only, omitted on list items.
»»» createdAt	string(date-time)	false	none	none
»»» updatedAt	string(date-time)	false	none	none

or

Name	Type	Required	Restrictions	Description
»» anonymous	KeyManagerPublicResponseSchema	false	none	Minimal developer-facing key manager view.
»»» id	string	false	none	The key manager's handle (unique per org). Not the internal database uuid.
»»» displayName	string	false	none	none
»»» tokenEndpoint	string(uri)	false	none	none

continued

Name	Type	Required	Restrictions	Description
» count	integer	false	none	Number of items returned in this page.
» pagination	Pagination	false	none	Standard pagination metadata returned with collection responses.
»» total	integer	true	none	Total number of records matching the query.
»» limit	integer	true	none	Maximum number of records returned in this response.
»» offset	integer	true	none	Number of records skipped before this page.

Get a key manager¶

GET /key-managers/{kmId}

Code samples

curl -X GET https://localhost:9543/api/v0.9/key-managers/{kmId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Retrieves a single key manager configuration by ID.

Authentication¶

Parameters

Name	In	Type	Required	Description
kmId	path	string	true	The key manager's handle (its `id` in request/response payloads), not the internal database uuid.

Example responses

200 Response

{
  "id": "asgardeo-prod",
  "displayName": "Asgardeo",
  "orgId": "org-12345",
  "enabled": true,
  "tokenEndpoint": "https://api.asgardeo.io/t/myorg/oauth2/token",
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Key manager configuration response.	KeyManagerResponseSchema
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Update a key manager¶

PUT /key-managers/{kmId}

Code samples

curl -X PUT https://localhost:9543/api/v0.9/key-managers/{kmId} \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Updates an existing key manager configuration. Accepts either a application/json body or a multipart/form-data upload with a keymanager YAML file. Only supplied fields are updated; omitted fields retain their stored values.

Payload

{
  "displayName": "Asgardeo",
  "id": "asgardeo-prod",
  "enabled": true,
  "tokenEndpoint": "https://api.asgardeo.io/t/myorg/oauth2/token"
}

displayName: Asgardeo
id: asgardeo-prod
enabled: true
tokenEndpoint: https://api.asgardeo.io/t/myorg/oauth2/token

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	KeyManagerUpdateRequest	false	Key manager update payload. All fields are optional; only supplied fields are updated. Submit as `application/json` or as `multipart/form-data` with a `keymanager` field containing a KeyManager YAML file.
kmId	path	string	true	The key manager's handle (its `id` in request/response payloads), not the internal database uuid.

Example responses

200 Response

{
  "id": "asgardeo-prod",
  "displayName": "Asgardeo",
  "orgId": "org-12345",
  "enabled": true,
  "tokenEndpoint": "https://api.asgardeo.io/t/myorg/oauth2/token",
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Key manager configuration response.	KeyManagerResponseSchema
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Delete a key manager¶

DELETE /key-managers/{kmId}

Code samples

curl -X DELETE https://localhost:9543/api/v0.9/key-managers/{kmId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Deletes a key manager configuration by ID.

Authentication¶

Parameters

Name	In	Type	Required	Description
kmId	path	string	true	The key manager's handle (its `id` in request/response payloads), not the internal database uuid.

Example responses

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
204	No Content	Key manager deleted successfully.	None
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse