> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API Key Management APIs

[Back to API List](https://koreai.mintlify.site/agent-platform/v1/apis.md)

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

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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

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

### Sample Response

```json theme={null}
{
  "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

```bash theme={null}
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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.