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

# Authentication API

> API reference for authentication, API keys, and user management on the Plexe Platform.

This document provides detailed information about the authentication endpoints of the Plexe Platform API.

## API Keys

### Create API Key

Creates a new API key for your account.

```http theme={null}
POST /auth/api-keys
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

#### Request Body

```json theme={null}
{
  "name": "Production Backend Key",
  "permission_level": "read_write"
}
```

| Parameter          | Type   | Required | Description                                   |
| ------------------ | ------ | -------- | --------------------------------------------- |
| `name`             | string | Yes      | Descriptive name for the API key              |
| `permission_level` | string | Yes      | Permission level: `read_only` or `read_write` |

#### Response

```json theme={null}
{
  "key_id": "key_abc123def456",
  "name": "Production Backend Key",
  "key": "plx_sk_987654321abcdefg...", // Full key shown ONLY once
  "permission_level": "read_write",
  "created_at": "2024-05-01T12:00:00Z",
  "expires_at": "2024-07-30T12:00:00Z", // Or null if no expiration
  "created_by": "user@example.com"
}
```

<Warning>
  The full API key value (`key` field) is displayed only once when the key is created. Store it securely as you won't be able to retrieve it again.
</Warning>

### List API Keys

Returns a list of all API keys for your account.

```http theme={null}
GET /auth/api-keys
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

#### Query Parameters

| Parameter | Type    | Required | Description                                              |
| --------- | ------- | -------- | -------------------------------------------------------- |
| `status`  | string  | No       | Filter by status: `active` or `revoked`                  |
| `limit`   | integer | No       | Maximum number of keys to return (default: 20, max: 100) |
| `offset`  | integer | No       | Number of keys to skip for pagination (default: 0)       |

#### Response

```json theme={null}
{
  "keys": [
    {
      "key_id": "key_abc123def456",
      "name": "Production Backend Key",
      "key_prefix": "plx_sk_9876", // First 4 digits + last 4 digits for identification
      "key_suffix": "defg",
      "permission_level": "read_write",
      "created_at": "2024-05-01T12:00:00Z",
      "expires_at": "2024-07-30T12:00:00Z",
      "last_used_at": "2024-05-10T15:22:43Z",
      "status": "active",
      "created_by": "user@example.com"
    },
    {
      "key_id": "key_ghi789jkl012",
      "name": "Development Key",
      "key_prefix": "plx_sk_1234",
      "key_suffix": "zyxw",
      "permission_level": "admin",
      "created_at": "2024-04-15T09:30:00Z",
      "expires_at": null,
      "last_used_at": "2024-05-11T08:17:22Z",
      "status": "active",
      "created_by": "admin@example.com"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}
```

### Get API Key

Retrieves details for a specific API key.

```http theme={null}
GET /auth/api-keys/{keyId}
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

#### Path Parameters

| Parameter | Type   | Required | Description                   |
| --------- | ------ | -------- | ----------------------------- |
| `keyId`   | string | Yes      | ID of the API key to retrieve |

#### Response

```json theme={null}
{
  "key_id": "key_abc123def456",
  "name": "Production Backend Key",
  "key_prefix": "plx_sk_9876",
  "key_suffix": "defg",
  "permission_level": "read_write",
  "created_at": "2024-05-01T12:00:00Z",
  "expires_at": "2024-07-30T12:00:00Z",
  "last_used_at": "2024-05-10T15:22:43Z",
  "status": "active",
  "created_by": "user@example.com",
  "usage_stats": {
    "requests_last_24h": 156,
    "requests_last_7d": 1287,
    "requests_last_30d": 4583
  }
}
```

### Update API Key

Updates the name or expiration of an API key.

```http theme={null}
PATCH /auth/api-keys/{keyId}
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

#### Path Parameters

| Parameter | Type   | Required | Description                 |
| --------- | ------ | -------- | --------------------------- |
| `keyId`   | string | Yes      | ID of the API key to update |

#### Request Body

```json theme={null}
{
  "name": "Updated Name",
  "expiration_days": 180  // Updates expiration to 180 days from now
}
```

| Parameter         | Type    | Required | Description                                       |
| ----------------- | ------- | -------- | ------------------------------------------------- |
| `name`            | string  | No       | New name for the API key                          |
| `expiration_days` | integer | No       | New expiration period (in days) from current date |

#### Response

```json theme={null}
{
  "key_id": "key_abc123def456",
  "name": "Updated Name",
  "key_prefix": "plx_sk_9876",
  "key_suffix": "defg",
  "permission_level": "read_write",
  "created_at": "2024-05-01T12:00:00Z",
  "expires_at": "2024-10-28T12:00:00Z", // Updated expiration
  "last_used_at": "2024-05-10T15:22:43Z",
  "status": "active",
  "created_by": "user@example.com"
}
```

<Note>
  You cannot change the permission level of an existing key. Create a new key with the desired permissions instead.
</Note>

### Revoke API Key

Revokes (invalidates) an API key, preventing its further use.

```http theme={null}
DELETE /auth/api-keys/{keyId}
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

#### Path Parameters

| Parameter | Type   | Required | Description                 |
| --------- | ------ | -------- | --------------------------- |
| `keyId`   | string | Yes      | ID of the API key to revoke |

#### Response

```json theme={null}
{
  "key_id": "key_abc123def456",
  "status": "revoked",
  "revoked_at": "2024-05-11T14:30:45Z"
}
```

<Warning>
  Revoking an API key is permanent and cannot be undone. Applications using the revoked key will immediately lose access.
</Warning>

## User Management

<Note>
  The following endpoint is available to retrieve user information for the currently authenticated user.
</Note>

### Get Current User

Returns information about the currently authenticated user.

```http theme={null}
GET /auth/user
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

#### Response

```json theme={null}
{
  "user_id": "user_abc123",
  "email": "user@example.com",
  "name": "Example User",
  "user_name": "user",
  "credits": 1000,
  "consumption": 50,
  "is_active": true,
  "has_api_key": true
}
```

<Note>
  Multi-Factor Authentication will be available in a future release.
</Note>

## Error Codes

| HTTP Status | Error Code          | Description              |
| ----------- | ------------------- | ------------------------ |
| 400         | `invalid_request`   | The request was invalid  |
| 401         | `unauthorized`      | Authentication failed    |
| 403         | `forbidden`         | Insufficient permissions |
| 404         | `not_found`         | Resource not found       |
| 409         | `resource_exists`   | Resource already exists  |
| 422         | `validation_failed` | Validation failed        |
| 429         | `rate_limited`      | Too many requests        |
| 500         | `server_error`      | Internal server error    |

## Rate Limits

Authentication endpoints have rate limits to prevent abuse:

* Key creation: 10 requests per hour
* Authentication attempts: 10 failed attempts per 15 minutes

Exceeding these limits will result in a `429 Too Many Requests` response.