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

# Model Permissions

> Restrict which models a key can call. Useful for staging keys, SFW-only deployments, or cost control.

## How it works

Each key has two optional fields:

* **`allowedModels`** — if non-empty, only these models are usable
* **`blockedModels`** — always rejected; takes precedence over allowed

Empty / null on both = all models allowed (default behavior).

## Set via dashboard

[dolphy.chat/settings/api-keys](https://dolphy.chat/settings/api-keys) →
Manage on the key → enter comma-separated model ids.

## Set via API

```bash theme={null}
curl -X PATCH https://dolphy.chat/api/account/api-keys/dpy_live_abc12345 \
  -H "Authorization: Bearer <firebase-id-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "allowedModels": ["lustify-v8", "dolphy-chat-1"],
    "blockedModels": ["nano-banana-pro", "gpt-image-2"]
  }'
```

Pass `null` or `[]` to clear either list.

## Common patterns

### "Only the cheap models on the dev key"

```json theme={null}
{
  "allowedModels": [
    "lustify-v8",
    "lustify-v7",
    "chroma",
    "z-image-turbo",
    "wai-Illustrious",
    "seedream-v4",
    "hidream"
  ]
}
```

All 1-credit/image models. Caps surprise spend on premium models.

### "Restrict to a curated set for a customer-facing app"

```json theme={null}
{
  "allowedModels": ["flux-2-pro", "seedream-v4", "recraft-v4", "gpt-image-2"]
}
```

Only models in `allowedModels` will be accepted by this key. Anything else returns 403.

### "Just chat for the AI agent"

```json theme={null}
{ "allowedModels": ["dolphy-chat-1"] }
```

Blocks every image and video model. Only chat allowed.

## When a request hits a blocked model

```json theme={null}
{
  "error": {
    "message": "This API key is not permitted to use model \"nano-banana-pro\".",
    "type": "model_forbidden",
    "code": null,
    "param": null
  }
}
```

Status: `403`. The customer should either change the model in their
request or update the key's permissions.

## Listing model ids

`GET /v1/models` returns all available model ids with their pricing and
capabilities. Use this to populate a model picker in your client.