API Key Management APIs

Back to API List

The following APIs can be used to create, revoke, and manage API keys and scopes for an application in the Agent Platform.

Prerequisites

Ensure the following before testing:

• Valid App ID
• Valid API Key (x-api-key header) with:
  • API Scope/Key = FULL permission

---

Create API Key

Provides an endpoint to create a new API key with an existing scope.

Specifications

Field	Value
Method	POST
Endpoint	https://<domain>/aaa/api/public/apps/{{appId}}/apikeys/create
Content-type	application/json
Authorization Header	x-api-key: <API-KEY>

Request Body

Field	Type	Description	Required
scope_name	string	Name of the existing scope	Yes
api_key_name	string	A new unique name of the API key to be created.	Yes

Sample Request

{
  "scope_name": "TestScope",
  "api_key_name": "MyKey"
}

curl --location 'https://<domain>/aaa/api/public/apps/aa-6b8e45ca-40a5-4667-a151-8225d0ffe592/apikeys/create' \
--header 'Content-Type: application/json' \
--header 'x-api-key: kg-xxxxx-xxxx-xxxx-b14e-8df48c7db7e3.1dd5d5bb-4d39-4ff5-b3bd-829856988e36' \
--data '{
 "scope_name": "TestScope",
 "api_key_name": "MyKey"
}
'

Success Response

Status: 201 Created

{
  "success": true,
  "api_key": {
    "apikey": "generated-key",
    "key_id": "ak-xxxx",
    "key_name": "MyKey",
    "scope_name": "TestScope"
  },
  {
    "scope":{
    <scope details>
    }
  }
}

Important Notes

• API key is returned only once. Store it securely.
• scope_name must already exist.
• api_key_name must be unique within the scope.

---

Revoke API Key

Deletes an existing API key permanently.

Specifications

Field	Value
Method	DELETE
Endpoint	https://<domain>/aaa/api/public/apps/{{appId}}/apikeys/{keyId}
Content-type	application/json
Authorization Header	x-api-key: <API-KEY>

Path Parameter

Field	Description
keyId	API Key ID to be deleted. Example: ak-a74c3b6b-xxxx-xxxx-bee8-963c95de7abc. The KeyId is different from the key.

Sample Request

curl --location --request DELETE 'https://<domain>/aaa/api/public/apps/aa-6b8e45ca-40a5-4667-a151-8225d0ffe592/apikeys/ak-b7031506-d4b5-40a1-9302-3686d13ebfd3' \
--header 'Content-Type: application/json' \
--header 'x-api-key: kg-aexxxx-xxxx-xxxxx-8df48c7db7e3.1dd5d5bb-4d39-4ff5-b3bd-829856988e36' \
--data ''

Success Response

Status: 200 OK

{
  "success": true,
  "revoked": {
    "key_id": "ak-xxxx",
    "status": "revoked"
  }
}

Important Notes

• This is a hard delete — revoked keys cannot be restored.
• Any ongoing requests using this key will fail immediately.

---

Get Scope Details

Fetches scope details and permissions. Returns details for valid keys and fails if the key is invalid or not linked.

Specifications

Field	Value
Method	GET
Endpoint	https://<domain>/aaa/api/public/apps/{appId}/scopes/{scopeId}
Content-type	application/json
Authorization Header	x-api-key: <API-KEY>

Sample cURL

curl --location 'https://<domain>/aaa/api/public/apps/{appId}/scopes/{scopeId}' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json'

Sample Response

{
  "success": true,
  "scope": {
    "scope_id": "as-3d2a9759-6461-xxxx-xxxx-29670d75c8f1",
    "scope_name": "AppScope",
    "description": "AppScope",
    "created_at": "2026-03-27T10:26:37.838Z",
    "permissions": {
      "APP_VIEW": "NO",
      "APP_EDIT": "NO",
      "APP_FULL": "NO",
      "AGENTS_VIEW": "NO",
      "AGENTS_EDIT": "NO",
      "AGENTS_FULL": "NO",
      "API_SCOPE_KEY_VIEW": "NO",
      "API_SCOPE_KEY_EDIT": "NO",
      "API_SCOPE_KEY_FULL": "NO",
      "RUN_API": "YES",
      "SESSION_CREATION": "YES",
      "DOCUMENT_UPLOAD": "YES",
      "SESSION_TERMINATION": "YES",
      "SESSIONS_LIST": "YES"
    }
  },
  "meta": {
    "requestId": "tr-44a2a3cc-6c60-41a5-9ee3-f1b7a5af47c2",
    "timestamp": "2026-03-30T13:08:51.257Z"
  }
}

---

Update Scope Permission

Updates permissions for a given scope. The API key used to invoke this API must belong to the scope that is being updated.

Specifications

Field	Value
Method	PUT
Endpoint	https://<domain>/aaa/api/public/apps/{appId}/scopes/{scopeId}
Content-type	application/json
Authorization Header	x-api-key: <API-KEY>

Request Body

Field	Description
permissions	List of permissions to be updated for this scope. Refer to the Get Scope Details sample for the list of permissions.

Sample cURL

ccurl --location --request PUT 'https://<domain>/aaa/api/public/apps/aa-6b8e45ca-40a5-4667-a151-8225d0ffe592/scopes/as-541baf27-a6e0-486c-a685-b06de501fe35' \
--header 'Content-Type: application/json' \
--header 'x-api-key: kg-XXXXXXX-2ba4-408f-b14e-8df48c7db7e3.1dd5d5bb-4d39-4ff5-b3bd-829856988e36' \
--data '{
  "permissions": {
    "DOCUMENT_UPLOAD": "NO"
  }
}'

Error Codes

Status Code	Description
401	Missing or invalid API key
403	The API key does not have the required permissions
404	Scope or API key not found
409	Duplicate API key name
429	API key limit reached