# API Key Management

Endpoints to manage your accounts API keys.

## List API Keys

`GET /v3/api-keys`

Returns all API keys belonging to the authenticated user with associated permissions.

**Responses**

- **200**: Ok
- **401**: Unauthorized

  | Field | Type | Description |
  |-------|------|-------------|
  | `code` | string | Error code |
  | `description` | string | Error description |


  Example (Invalid JWT):
  ```json
  {"code":"INVALID_JWT_TOKEN","description":"Invalid JWT"}
  ```

**Example**

```bash
curl "https://api.demo.omniaexchange.com/api/v3/api-keys" \
  -H "Authorization: Bearer <token>"
```

---

## Create API Key

`POST /v3/api-keys`

Creates a new API key with the specified label and permissions. The requested permissions must be a subset of the permissions on the API key used to authenticate this request. Store the returned secret securely as it will not be shown again.

**Request Body** _(required)_

  | Field | Type | Description |
  |-------|------|-------------|
  | `label` | string | Label for the new API key (e.g. `Trading Key`) |
  | `permissions` | string[] | Permissions to grant to the new API key. Must be a subset of the permissions on the API key used to make this request. |

**Responses**

- **201**: Created

  | Field | Type | Description |
  |-------|------|-------------|
  | `apiKeyId` | string | The API key id (e.g. `QNl8Xfl729CJlNgwkA329EL1D8z8BAQ2`) |
  | `apiKeySecret` | string | The API key secret. Store this securely, it will not be shown again. (e.g. `u0WgWWLXYhcS+UnAGk2H+eZ3JZp1P4kpUxcoNitzu3U=`) |
  | `label` | string | Label for the new API key (e.g. `Trading Key`) |
  | `permissions` | string[] | Permissions granted to this API key |

- **400**: Bad request

  | Field | Type | Description |
  |-------|------|-------------|
  | `code` | string | Error code |
  | `description` | string | Error description |


  Example (Invalid schema):
  ```json
  {"code":"INVALID_SCHEMA","description":"Missing or malformed schema"}
  ```
- **401**: Unauthorized

  | Field | Type | Description |
  |-------|------|-------------|
  | `code` | string | Error code |
  | `description` | string | Error description |


  Example (Invalid JWT):
  ```json
  {"code":"INVALID_JWT_TOKEN","description":"Invalid JWT"}
  ```
- **403**: Requested permissions exceed those of the authenticating API key

  | Field | Type | Description |
  |-------|------|-------------|
  | `code` | string | Error code |
  | `description` | string | Error description |


  Example (Invalid permissions):
  ```json
  {"code":"INVALID_PERMISSIONS","description":"Invalid permissions"}
  ```
- **500**: Internal server error

  | Field | Type | Description |
  |-------|------|-------------|
  | `code` | string | Error code |
  | `description` | string | Error description |


  Example (Internal error):
  ```json
  {"code":"INTERNAL_SERVER_ERROR","description":"Internal Server Error"}
  ```

**Example**

```bash
curl -X POST "https://api.demo.omniaexchange.com/api/v3/api-keys" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"label": "Trading Key", "permissions": "<permissions>"}'
```

---

## Rotate API Key

`POST /v3/api-keys/{apiKeyId}/rotate`

Generates a new secret for the specified API key. The old secret and jwt is immediately invalidated. Store the new secret securely as it will not be shown again.

**Parameters**

| Name | In | Required | Type | Description |
|------|-----|----------|------|-------------|
| `apiKeyId` | path | Yes | string | The id of the API key to rotate |

**Responses**

- **200**: Ok

  | Field | Type | Description |
  |-------|------|-------------|
  | `apiKeyId` | string | The API key id (e.g. `QNl8Xfl729CJlNgwkA329EL1D8z8BAQ2`) |
  | `apiKeySecret` | string | The new API key secret. Store this securely, it will not be shown again. (e.g. `u0WgWWLXYhcS+UnAGk2H+eZ3JZp1P4kpUxcoNitzu3U=`) |

- **401**: Unauthorized

  | Field | Type | Description |
  |-------|------|-------------|
  | `code` | string | Error code |
  | `description` | string | Error description |


  Example (Invalid JWT):
  ```json
  {"code":"INVALID_JWT_TOKEN","description":"Invalid JWT"}
  ```
- **403**: Invalid permissions

  | Field | Type | Description |
  |-------|------|-------------|
  | `code` | string | Error code |
  | `description` | string | Error description |


  Example (Invalid permissions):
  ```json
  {"code":"INVALID_PERMISSIONS","description":"Invalid permissions"}
  ```
- **404**: API key not found or does not belong to this user

  | Field | Type | Description |
  |-------|------|-------------|
  | `code` | string | Error code |
  | `description` | string | Error description |


  Example (Not found):
  ```json
  {"code":"NOT_FOUND","description":"Not Found"}
  ```
- **500**: Internal server error

  | Field | Type | Description |
  |-------|------|-------------|
  | `code` | string | Error code |
  | `description` | string | Error description |


  Example (Internal error):
  ```json
  {"code":"INTERNAL_SERVER_ERROR","description":"Internal Server Error"}
  ```

**Example**

```bash
curl -X POST "https://api.demo.omniaexchange.com/api/v3/api-keys/{apiKeyId}/rotate" \
  -H "Authorization: Bearer <token>"
```

---