# API Keys API

Generate and manage programmatic access keys

Create and manage API keys for programmatic access. Generate new keys with custom names and optional expiration dates, list all active keys, update key metadata, and revoke keys when no longer needed. Each key can be scoped to specific permissions for security.

## Available Endpoints

| Method | Endpoint                                                | Description          |
| ------ | ------------------------------------------------------- | -------------------- |
| `POST` | [`/api/auth/api-key/create`](#post-apiauthapikeycreate) | Create a new API key |
| `GET`  | [`/api/auth/api-key/list`](#get-apiauthapikeylist)      | List all API keys    |
| `GET`  | [`/api/auth/api-key/get`](#get-apiauthapikeyget)        | Get API key details  |
| `POST` | [`/api/auth/api-key/update`](#post-apiauthapikeyupdate) | Update an API key    |
| `POST` | [`/api/auth/api-key/delete`](#post-apiauthapikeydelete) | Delete an API key    |

## Endpoints

### POST /api/auth/api-key/create

Create a new API key

Create a new API key for programmatic API access. The full key is only returned once - store it securely.

**Auth:** bearer · **Scopes:** `api-keys:write`

#### Body parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `name` | string | yes | Human-readable name for the key | `My API Key` |
| `expiresIn` | number | no | Expiration time in seconds (optional) | `2592000` |
| `metadata` | object | yes |  |  |

#### Request example

**curl**

```bash
curl -X POST "https://api.indexhog.com/api/auth/api-key/create" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"name":"My API Key","expiresIn":2592000,"metadata":{"scopes":["user:read","projects:read"],"organizationId":"string"}}'
```

**JavaScript**

```javascript
const response = await fetch("https://api.indexhog.com/api/auth/api-key/create", {
method: "POST",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  "name": "My API Key",
  "expiresIn": 2592000,
  "metadata": {
    "scopes": [
      "user:read",
      "projects:read"
    ],
    "organizationId": "string"
  }
}),
});

const data = await response.json();
console.log(data);
```

#### Response `200` — API key created successfully

```json
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "key": "tkn_1234567890abcdef...",
  "id": "ak_abc123",
  "name": "My API Key"
}
}
```

#### Response `401` — Unauthorized - Invalid or missing authentication

```json
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
```

#### Response `403` — Forbidden - Insufficient permissions

```json
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
```

### GET /api/auth/api-key/list

List all API keys

Get all API keys for the authenticated user. Note: The full key value is not returned.

**Auth:** bearer · **Scopes:** `api-keys:read`

#### Request example

**curl**

```bash
curl -X GET "https://api.indexhog.com/api/auth/api-key/list" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"
```

**JavaScript**

```javascript
const response = await fetch("https://api.indexhog.com/api/auth/api-key/list", {
method: "GET",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
});

const data = await response.json();
console.log(data);
```

#### Response `200` — API keys retrieved successfully

```json
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": [
  {
    "id": "ak_abc123",
    "name": "My API Key",
    "start": "tkn_...xyz",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "expiresAt": "2024-12-31T23:59:59.000Z",
    "lastUsedAt": "2024-01-15T10:30:00.000Z",
    "enabled": true,
    "scopes": [
      "user:read",
      "projects:read"
    ],
    "metadata": {}
  }
]
}
```

#### Response `401` — Unauthorized - Invalid or missing authentication

```json
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
```

#### Response `403` — Forbidden - Insufficient permissions

```json
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
```

### GET /api/auth/api-key/get

Get API key details

Get details of a specific API key by ID.

**Auth:** bearer · **Scopes:** `api-keys:read`

#### Query parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `id` | string | yes | API Key ID | `ak_abc123` |

#### Request example

**curl**

```bash
curl -X GET "https://api.indexhog.com/api/auth/api-key/get" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"
```

**JavaScript**

```javascript
const response = await fetch("https://api.indexhog.com/api/auth/api-key/get", {
method: "GET",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
});

const data = await response.json();
console.log(data);
```

#### Response `200` — API key retrieved successfully

```json
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "id": "ak_abc123",
  "name": "My API Key",
  "start": "tkn_...xyz",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "lastUsedAt": "2024-01-15T10:30:00.000Z",
  "enabled": true,
  "scopes": [
    "user:read",
    "projects:read"
  ],
  "metadata": {}
}
}
```

#### Response `401` — Unauthorized - Invalid or missing authentication

```json
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
```

#### Response `403` — Forbidden - Insufficient permissions

```json
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
```

### POST /api/auth/api-key/update

Update an API key

Update an existing API key's name, enabled status, or scopes.

**Auth:** bearer · **Scopes:** `api-keys:write`

#### Body parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `id` | string | yes | API Key ID | `ak_abc123` |
| `name` | string | no |  | `Updated Key Name` |
| `enabled` | boolean | no | Enable or disable the key | `true` |

#### Request example

**curl**

```bash
curl -X POST "https://api.indexhog.com/api/auth/api-key/update" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"id":"ak_abc123","name":"Updated Key Name","enabled":true}'
```

**JavaScript**

```javascript
const response = await fetch("https://api.indexhog.com/api/auth/api-key/update", {
method: "POST",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  "id": "ak_abc123",
  "name": "Updated Key Name",
  "enabled": true
}),
});

const data = await response.json();
console.log(data);
```

#### Response `200` — API key updated successfully

```json
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "id": "ak_abc123",
  "name": "My API Key",
  "start": "tkn_...xyz",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "lastUsedAt": "2024-01-15T10:30:00.000Z",
  "enabled": true,
  "scopes": [
    "user:read",
    "projects:read"
  ],
  "metadata": {}
}
}
```

#### Response `401` — Unauthorized - Invalid or missing authentication

```json
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
```

#### Response `403` — Forbidden - Insufficient permissions

```json
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
```

### POST /api/auth/api-key/delete

Delete an API key

Permanently delete an API key. This action cannot be undone.

**Auth:** bearer · **Scopes:** `api-keys:delete`

#### Body parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `id` | string | yes | API Key ID to delete | `ak_abc123` |

#### Request example

**curl**

```bash
curl -X POST "https://api.indexhog.com/api/auth/api-key/delete" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"id":"ak_abc123"}'
```

**JavaScript**

```javascript
const response = await fetch("https://api.indexhog.com/api/auth/api-key/delete", {
method: "POST",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  "id": "ak_abc123"
}),
});

const data = await response.json();
console.log(data);
```

#### Response `200` — API key deleted successfully

```json
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "success": true
}
}
```

#### Response `401` — Unauthorized - Invalid or missing authentication

```json
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
```

#### Response `403` — Forbidden - Insufficient permissions

```json
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
```