Hook Keys

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.

Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.

List all keys
OAuth 2.0:
  • okta.inlineHooks.read

Lists all keys

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/hook-keys
Request samples 
Response samples 
application/json
[
  • {
    • "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"
    }
]
Create a key
OAuth 2.0: 
  • okta.inlineHooks.manage
Creates a key for use with other parts of the application, such as inline hooks




Note:  Use the key name to access this key for inline hook operations.




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


 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.




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




Request 
Request Body schema: application/json
required
name
string  [ 1 .. 255 ] characters  unique 
Display name for the key


 
Responses 
200
Success


400
Bad Request


403
Forbidden


429
Too Many Requests


post/api/v1/hook-keys
Request samples 
application/json
{
  • "name": "string"
}
Response samples 
application/json
{
  • "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`"
    }
}
Retrieve a public key
OAuth 2.0: 
  • okta.inlineHooks.read
Retrieves a public key by keyId




Note: keyId is the alias of the public key.




Request 
path Parameters
keyId
required
string
id" of the Public Key


 
 Example:  FcH2P9Eg7wr0o8N2FuV0
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/hook-keys/public/{keyId}
Request samples 
Response samples 
application/json
{
  • "_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`"
    }
}
Retrieve a key by ID
OAuth 2.0: 
  • okta.inlineHooks.read
Retrieves the public portion of the Key object using the id parameter




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.




Request 
path Parameters
id
string
A valid key ID


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/hook-keys/{id}
Request samples 
Response samples 
application/json
{
  • "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"
}
Replace a key
OAuth 2.0: 
  • okta.inlineHooks.manage
Replaces a key by id


This request replaces existing properties after passing validation.




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




Request 
path Parameters
id
required
string
ID of the Hook Key


 
 Example:  XreKU5laGwBkjOTehusG
Request Body schema: application/json
required
name
string  [ 1 .. 255 ] characters  unique 
Display name for the key


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/hook-keys/{id}
Request samples 
application/json
{
  • "name": "string"
}
Response samples 
application/json
{
  • "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"
}
Delete a key
OAuth 2.0: 
  • okta.inlineHooks.manage
Deletes a key by id. After being deleted, the key is unrecoverable.


As a safety precaution, only keys that aren't being used are eligible for deletion.


Request 
path Parameters
id
required
string
ID of the Hook Key


 
 Example:  XreKU5laGwBkjOTehusG
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/hook-keys/{id}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}