> ## Documentation Index
> Fetch the complete documentation index at: https://dev-doc.dualmindlab.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Providers API

> Admin AI provider and API key management — list providers, manage API keys, key rotation and health tracking.

## Providers

### GET /api/admin/providers

List all AI providers with key counts.

### Response

```json filename="Response" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "success": true,
  "data": [
    {
      "provider_name": "groq",
      "display_name": "Groq",
      "is_enabled": true,
      "priority": 1,
      "key_count": 3,
      "created_at": "2025-01-01T00:00:00Z"
    },
    {
      "provider_name": "bytez",
      "display_name": "Bytez",
      "is_enabled": true,
      "priority": 2,
      "key_count": 1,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}
```

### POST /api/admin/providers

Create a new provider.

```json filename="Request Body" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "providerName": "openai",
  "displayName": "OpenAI",
  "isEnabled": true,
  "priority": 3
}
```

### PUT /api/admin/providers/{name}

Update a provider by name.

```json filename="Request Body" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "displayName": "OpenAI GPT",
  "isEnabled": false,
  "priority": 5
}
```

## API keys

### GET /api/admin/providers/{name}/keys

Get all API keys for a provider (includes full key for admin).

### Response

```json filename="Response" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "success": true,
  "data": [
    {
      "key_id": "k1-uuid",
      "provider_name": "groq",
      "api_key": "gsk_full_key_visible_to_admin",
      "display_mask": "...abc4",
      "is_active": true,
      "failure_count": 0,
      "total_calls": 1542,
      "last_used_at": "2025-01-15T09:45:00Z",
      "cooldown_until": null
    }
  ]
}
```

### POST /api/admin/providers/{name}/keys

Add a new API key to a provider.

```json filename="Request Body" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "apiKey": "gsk_your_new_api_key_here",
  "isActive": true
}
```

The key is stored with an auto-generated `display_mask` (last 4 characters).

### PUT /api/admin/keys/{id}/status

Toggle a key's active status.

```json filename="Request Body" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "isActive": false
}
```

### DELETE /api/admin/keys/{id}

Delete an API key by UUID.

## Key rotation behavior

The `ProviderConfigService` manages automatic key rotation:

1. **On each request**: Selects the active key with the lowest failure count
2. **On auth/rate-limit error**: Marks key as failed, immediately rotates to next key
3. **On transient error**: Rotates once, then throws if second key also fails
4. **Cooldown**: Keys can be placed in cooldown until a specific timestamp
5. **Success reporting**: Resets failure count on successful API call