Key Management API

The Okta Key Management API provides a CRUD interface for JSON Web Keys (JWK) used with other parts of the application, such as inline hooks. For information on how to create inline hooks, see Inline hooks management API.

Get started

Explore the Key Management API: (opens new window)

Key Management operations

The Key Management API has the following CRUD operations:

• Create a key
• Get a key
• List keys
• Get a public key
• Update a key
• Delete a key

Create a key

POST /api/v1/hook-keys

To create a key, use the key request object as the JSON payload. This JSON object represents the required information about the key that you are creating.

Note: The new key that you create is accessed by the key name for use with inline hooks.

The total number of keys that you can create in an Okta org is limited to 50.

Request parameters

Parameter	Description	Param Type	DataType	Required
key	A valid request object that specifies the details of the key that you create	Body	key request object	TRUE

Response parameters

The response is a Key object that represents the key that you create. The id property in the response serves as the unique ID for the key, which you can specify when invoking other CRUD operations. The keyId provided in the response is the alias of the public key that you can use to get details of the public key data in a separate call.

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "name" : "Test Name",
}' "https://${yourOktaDomain}/api/v1/hook-keys"

Response example

{
  "id": "HKY1p7jWLndGQV9M60g4",
  "keyId": "7fbc27fd-e3df-4522-86bf-1930110256ad",
  "name": "My new key",
  "created": "2022-08-31T18:09:58.000Z",
  "lastUpdated": "2022-08-31T18:09:58.000Z",
  "isUsed": false,
  "_embedded": {
    "kty": "RSA",
    "alg": "RSA",
    "kid": "7fbc27fd-e3df-4522-86bf-1930110256ad",
    "use": null,
    "e": "AQAB",
    "n": "2naqCnv6r4xNQs7207lRtKQvdtnlVND-8k5iYBIiqoKGY3CqUmRm1jleoOniiQoMkFX8Wj2DmVqr002efF3vOQ7_gjtTatBTVUNbNIQLybun4dkVoUtfP7pRc5SLpcP3eGPRVar734ZrpQXzmCEdpqBt3jrVjwYjNE5DqOjbYXFJtMsy8CWE9LRJ3kyHEoHPzo22dG_vMrXH0_sAQoCk_4TgNCbvyzVmGVYXI_BkUnp0hv2pR4bQVRYzGB9dKJdctOh8zULqc_EJ8tiYsS05YnF7whrWEyARK0rH-e4d4W-OmBTga_zhY4kJ4NsoQ4PyvcatZkxjPO92QHQOFDnf3w"
  }
}

Note: The keyId is the alias of the public key that you can use to retrieve the public key.

Get a key

GET /api/v1/hook-keys/${id}

Request parameters

Parameter	Description	Param Type	DataType	Required
id	A valid key ID	Path	String	TRUE

Note: The ?expand=publickey query parameter optionally returns the full object including the details of the public key in the response body's _embedded property.

Response parameters

The response is a Key object that represents the key that matches the id that you specify.

Request example

curl -v -X GET \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/hook-keys/${id}"

Response example

{
  "id": "HKY1p7jWLndGQV9M60g4",
  "keyId": "7fbc27fd-e3df-4522-86bf-1930110256ad",
  "name": "My new key",
  "created": "2022-08-31T18:09:58.000Z",
  "lastUpdated": "2022-08-31T18:09:58.000Z",
  "isUsed": false,
  "_embedded": {
    "kty": "RSA",
    "alg": "RSA",
    "kid": "7fbc27fd-e3df-4522-86bf-1930110256ad",
    "use": null,
    "e": "AQAB",
    "n": "2naqCnv6r4xNQs7207lRtKQvdtnlVND-8k5iYBIiqoKGY3CqUmRm1jleoOniiQoMkFX8Wj2DmVqr002efF3vOQ7_gjtTatBTVUNbNIQLybun4dkVoUtfP7pRc5SLpcP3eGPRVar734ZrpQXzmCEdpqBt3jrVjwYjNE5DqOjbYXFJtMsy8CWE9LRJ3kyHEoHPzo22dG_vMrXH0_sAQoCk_4TgNCbvyzVmGVYXI_BkUnp0hv2pR4bQVRYzGB9dKJdctOh8zULqc_EJ8tiYsS05YnF7whrWEyARK0rH-e4d4W-OmBTga_zhY4kJ4NsoQ4PyvcatZkxjPO92QHQOFDnf3w"
  }
}

List keys

GET /api/v1/hook-keys

Lists all keys

Request examples

curl -v -X GET \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/hook-keys"

Response example

[{
  "id": "HKY1i2htmXF5UNQhL0g4",
  "keyId": "bb5bed7d-6e4d-488f-9c86-59b93a2bb3fb",
  "name": "My new key",
  "created": "2022-08-22T16:34:33.000Z",
  "lastUpdated": "2022-08-22T16:34:33.000Z",
  "isUsed": true
}, {
  "id": "HKY1p7jWLndGQV9M60g4",
  "keyId": "7fbc27fd-e3df-4522-86bf-1930110256ad",
  "name": "Test Key",
  "created": "2022-08-31T18:09:58.000Z",
  "lastUpdated": "2022-08-31T18:09:58.000Z",
  "isUsed": false
}]

Get a public key

GET /api/v1/hook-keys/${keyId}

Retrieves the public portion of the Key object using the keyId parameter

Request parameters

Parameter	Description	Param Type	DataType	Required
keyId	A valid key ID	Path	String	TRUE

Note: keyId is the alias of the public key.

Response parameters

The response represents the key that matches the keyId that you specify.

Request example

curl -v -X GET \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/hook-keys/${KeyId}"

Response example

You can find the details of the response in public key details.

{
  "kty": "RSA",
  "alg": "RSA",
  "kid": "bb5bed7d-6e4d-488f-9c86-59b93a2bb3fb",
  "use": null,
  "e": "AQAB",
  "n": "togCavBd7yQ7fuTEdvRURfK04LSgxqbKlptc7Gy9l6Swk2nhJbfIuB2Eezrn_JX-Azh-8usMMKau8vkq6AR2pW5mgDNIJG0OnCdwK24BdohxWlVQRZ5fD5DYg-noWwIbDjCGxMq3BKhOJP8cGAXx-olfrkC2NRy-HiJZOPiONII_GnlBiVS29BmULbbhKNeSGtoe90tR_OsXozfBsRRKFnF4ewQG3QwE23q6W3uNsUTr87fD9OO0FxNXyjnR3UrMTq36W6QLhqgLxlSiqxXGALnhK5z7WfXxyGfYrytrg2tFIhiHi0hT300xRI4A6SqhPFSCegx_O8iZQlTeaiHgjQ"
}

Update a key

PUT /api/v1/hook-keys/${id}

Request parameters

Parameter	Description	Param Type	DataType	Required
id	The ID of the key that you want to update	Path	String	TRUE
key request	An object that represents the updated properties that you want to apply	Body	key request object	TRUE

The submitted key request replaces the existing properties after passing validation.

Note: The only parameter that you can update is the name of the key, which needs to be unique at all times.

Response parameters

The response is a Key object that represents the updated key.

Request example

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "name" : "Test key"
}' "https://${yourOktaDomain}/api/v1/hook-keys/${id}"

Response example

{
  "id": "HKY1p7jWLndGQV9M60g4",
  "keyId": "7fbc27fd-e3df-4522-86bf-1930110256ad",
  "name": "My updated new key",
  "created": "2022-08-31T18:09:58.000Z",
  "lastUpdated": "2022-08-31T18:16:59.000Z",
  "isUsed": false,
  "_embedded": {
    "kty": "RSA",
    "alg": "RSA",
    "kid": "7fbc27fd-e3df-4522-86bf-1930110256ad",
    "use": null,
    "e": "AQAB",
    "n": "2naqCnv6r4xNQs7207lRtKQvdtnlVND-8k5iYBIiqoKGY3CqUmRm1jleoOniiQoMkFX8Wj2DmVqr002efF3vOQ7_gjtTatBTVUNbNIQLybun4dkVoUtfP7pRc5SLpcP3eGPRVar734ZrpQXzmCEdpqBt3jrVjwYjNE5DqOjbYXFJtMsy8CWE9LRJ3kyHEoHPzo22dG_vMrXH0_sAQoCk_4TgNCbvyzVmGVYXI_BkUnp0hv2pR4bQVRYzGB9dKJdctOh8zULqc_EJ8tiYsS05YnF7whrWEyARK0rH-e4d4W-OmBTga_zhY4kJ4NsoQ4PyvcatZkxjPO92QHQOFDnf3w"
  }
}

Delete a key

DELETE /api/v1/hook-keys/${id}

Request parameters

Parameter	Description	Param Type	DataType	Required
id	The ID of the key to delete	Path	String	TRUE

Deletes the key that matches the provided id. After it's deleted, the key is unrecoverable. As a safety precaution, only keys that aren't being used are eligible for deletion.

Response parameters

All responses return a 204 status with no content.

Request example

curl -v -X DELETE \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/hook-keys/${id}"

Response example

204 with no content

Key Management objects

The Key Management API has the following objects:

• Key Request object
• Key object
• Public key details

Key Request object

Property	Description	DataType	Nullable	Unique	ReadOnly	Validation
name	Display name for the key	String	FALSE	TRUE	FALSE	Must be between one and 255 characters in length

{
    "name" : "My new key"
}

Key object

Property	Description	DataType	Nullable	Unique	ReadOnly	Validation
id	Unique key	String	FALSE	TRUE	TRUE	System assigned
keyId	Alias of the public key	String	FALSE	TRUE	TRUE	System assigned
name	Display name for the key	String	FALSE	TRUE	FALSE	Must be between one and 255 characters in length
isUsed	Declares if this item is currently in use by other applications	String(Boolean)	FALSE	FALSE	TRUE	System assigned
created	Date of key creation	String (Date)	TRUE	FALSE	TRUE	System assigned
lastUpdated	Date of key update	String (Date)	TRUE	FALSE	TRUE	System assigned
_embedded	Public Key Details	JSON	FALSE	TRUE	TRUE	System assigned

{
  "id": "HKY1p7jWLndGQV9M60g4",
  "keyId": "7fbc27fd-e3df-4522-86bf-1930110256ad",
  "name": "My new key",
  "created": "2022-08-31T18:09:58.000Z",
  "lastUpdated": "2022-08-31T18:09:58.000Z",
  "isUsed": false,
  "_embedded": {
    "kty": "RSA",
    "alg": "RSA",
    "kid": "7fbc27fd-e3df-4522-86bf-1930110256ad",
    "use": null,
    "e": "AQAB",
    "n": "2naqCnv6r4xNQs7207lRtKQvdtnlVND-8k5iYBIiqoKGY3CqUmRm1jleoOniiQoMkFX8Wj2DmVqr002efF3vOQ7_gjtTatBTVUNbNIQLybun4dkVoUtfP7pRc5SLpcP3eGPRVar734ZrpQXzmCEdpqBt3jrVjwYjNE5DqOjbYXFJtMsy8CWE9LRJ3kyHEoHPzo22dG_vMrXH0_sAQoCk_4TgNCbvyzVmGVYXI_BkUnp0hv2pR4bQVRYzGB9dKJdctOh8zULqc_EJ8tiYsS05YnF7whrWEyARK0rH-e4d4W-OmBTga_zhY4kJ4NsoQ4PyvcatZkxjPO92QHQOFDnf3w"
  }
}

Public Key Details

The Public Key Details are defined in the _embedded property of the Key object.

Property	Description	DataType	Nullable	Unique	ReadOnly	Validation
kty	Cryptographic algorithm family for the certificate's keypair	String	FALSE	FALSE	TRUE	System assigned
alg	Algorithm used in the key	String	FALSE	FALSE	TRUE	System assigned
kid	Unique identifier for the certificate	String	FALSE	TRUE	TRUE	System assigned
use	Acceptable use of the certificate	String	TRUE	FALSE	TRUE	System assigned
e	RSA key value (exponent) for key binding	String	FALSE	FALSE	TRUE	System assigned
n	RSA key value (modulus) for key binding	String	FALSE	FALSE	TRUE	System assigned

{
  "_embedded": {
    "kty": "RSA",
    "alg": "RSA",
    "kid": "7fbc27fd-e3df-4522-86bf-1930110256ad",
    "use": null,
    "e": "AQAB",
    "n": "2naqCnv6r4xNQs7207lRtKQvdtnlVND-8k5iYBIiqoKGY3CqUmRm1jleoOniiQoMkFX8Wj2DmVqr002efF3vOQ7_gjtTatBTVUNbNIQLybun4dkVoUtfP7pRc5SLpcP3eGPRVar734ZrpQXzmCEdpqBt3jrVjwYjNE5DqOjbYXFJtMsy8CWE9LRJ3kyHEoHPzo22dG_vMrXH0_sAQoCk_4TgNCbvyzVmGVYXI_BkUnp0hv2pR4bQVRYzGB9dKJdctOh8zULqc_EJ8tiYsS05YnF7whrWEyARK0rH-e4d4W-OmBTga_zhY4kJ4NsoQ4PyvcatZkxjPO92QHQOFDnf3w"
  }
}