Skip to main content
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

FieldValue
MethodPOST
Endpointhttps://<domain>/aaa/api/public/apps/{{appId}}/apikeys/create
Content-typeapplication/json
Authorization Headerx-api-key: <API-KEY>

​
Request Body

FieldTypeDescriptionRequired
scope_namestringName of the existing scopeYes
api_key_namestringA 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

FieldValue
MethodDELETE
Endpointhttps://<domain>/aaa/api/public/apps/{{appId}}/apikeys/{keyId}
Content-typeapplication/json
Authorization Headerx-api-key: <API-KEY>

​
Path Parameter

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

FieldValue
MethodGET
Endpointhttps://<domain>/aaa/api/public/apps/{appId}/scopes/{scopeId}
Content-typeapplication/json
Authorization Headerx-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

FieldValue
MethodPUT
Endpointhttps://<domain>/aaa/api/public/apps/{appId}/scopes/{scopeId}
Content-typeapplication/json
Authorization Headerx-api-key: <API-KEY>

​
Request Body

FieldDescription
permissionsList 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 CodeDescription
401Missing or invalid API key
403The API key does not have the required permissions
404Scope or API key not found
409Duplicate API key name
429API key limit reached