API Key Management¶

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 (apikey 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	`/apikeys/create`
Content-type	application/json
Authorization Header	apikey: `<API-KEY>`

Request Body¶

Field	Type	Description	Required
scope_name	string	Name of the existing scope	Yes
api_key_name	string	Name of the API key to be created	Yes

Sample Request¶

{
 "scope_name": "Scope 2",
 "api_key_name": "Public 2"
}

Success Response¶

Status: 201 Created

{
 "success": true,
 "api_key": {
   "apikey": "generated-key",
   "key_id": "ak-xxxx",
   "key_name": "Public 2",
   "scope_name": "Scope 2"
 }
}

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.

Field	Value
Method	DELETE
Endpoint	`/apikeys/{keyId}`
Content-type	application/json
Authorization Header	apikey: `<API-KEY>`

Path Parameter¶

Field	Description
keyId	API Key Id to be deleted. (Example: `ak-a74c3b6b-cb71-48da-bee8-963c95de7abc`)

Success Response¶

Status: 200 OK

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

Important Notes¶

This is a hard delete, and revoked keys can't 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.

Specification¶

Field	Value
Method	GET
Endpoint	`/apps/{appId}/scopes/{scopeId}`
Content-type	application/json
Authorization Header	apikey: `<API-KEY>`

Sample cURL¶

curl --location 'https://<domain>/api/public/apps/{appId}/scopes/{scopeId}' \
--header 'apikey: <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.

Specification¶

Field	Value
Method	PUT
Endpoint	`/apps/{appId}/scopes/{scopeId}`
Content-type	application/json
Authorization Header	apikey: `<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¶

curl --location --request PUT 'https://domain/api/public/apps/{appId}/scopes/{scopeId}' \
--header 'apikey: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
 "permissions": {
   "API_SCOPE_KEY": "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

Send Feedback