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

# API Key Management APIs

<Badge icon="arrow-left" color="gray">[Back to API List](/agent-platform/apis)</Badge>

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                              |