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

# Scopes de API Key

> Permisos de clave en Platform API: API keys, billing y equipo.

<Tip>
  La clave devuelta en `POST /v1/platform/verify` tiene **scopes vacíos** = acceso **ADMIN** (todo) durante onboarding. En producción, crea claves restringidas vía `POST /v1/platform/api-keys`.
</Tip>

## En resumen

* Cada API key pertenece a **un workspace**.
* Scopes vacíos al crear = **acceso total** (equivalente a ADMIN).
* **API keys** usan `api_keys:read` y `api_keys:manage`
* **Billing** (plan, saldo, tarjetas, historial de créditos) usa `billing:read` y `billing:manage`.
* **Equipo** (miembros e invitaciones) usa `workspace:members:read` y `workspace:members:manage` .
* Mensajería usa scopes por canal documentados en cada API.

Guía general: [API Keys](/es/guides/api-key/index).

***

## Scopes por área

| Área                               | Lectura                  | Gestión                                                    |
| ---------------------------------- | ------------------------ | ---------------------------------------------------------- |
| API keys (`/v1/platform/api-keys`) | `api_keys:read`          | `api_keys:manage`                                          |
| Billing (plan, saldo, tarjetas)    | `billing:read`           | `billing:manage`                                           |
| Uso de créditos (`/credits/usage`) | `billing:read`           | —                                                          |
| Miembros e invitaciones            | `workspace:members:read` | `workspace:members:manage`                                 |
| Workspaces (`/v1/workspaces`)      | `workspace:read`         | `workspace:create`, `workspace:update`, `workspace:delete` |

Con `sessionToken` de login, miembros **OWNER/ADMIN** pueden operar billing, claves y equipo sin scopes en la API key.

***

## Cómo enviar la clave

```http theme={null}
Authorization: Bearer sk_live_xxxxx
```

Alternativa: `x-api-key: sk_live_xxxxx`.

***

## Rutas de API keys (`/v1/platform/api-keys`)

| Método | Ruta                               | Scope             | Descripción                         |
| ------ | ---------------------------------- | ----------------- | ----------------------------------- |
| GET    | `/v1/platform/api-keys`            | `api_keys:read`   | Lista (`?includeRevoked=true`)      |
| POST   | `/v1/platform/api-keys`            | `api_keys:manage` | Crear (`key` **una vez**)           |
| GET    | `/v1/platform/api-keys/:id`        | `api_keys:read`   | Detalle (sin plaintext)             |
| PATCH  | `/v1/platform/api-keys/:id`        | `api_keys:manage` | Nombre, scopes, límites, instancias |
| POST   | `/v1/platform/api-keys/:id/revoke` | `api_keys:manage` | Soft revoke                         |
| DELETE | `/v1/platform/api-keys/:id`        | `api_keys:manage` | Alias del revoke                    |

<Note>
  Claves antiguas con solo `billing:read` / `billing:manage` siguen funcionando en rutas de API keys hasta migrar scopes.
</Note>

### Seguridad

* **CANNOT\_REVOKE\_SELF** — no revocar la clave de la petición.
* **API\_KEY\_REVOKED** — clave revocada no se puede editar.

### Crear clave restringida

```json theme={null}
{
  "name": "Bot producción",
  "environment": "LIVE",
  "scopes": ["whatsapp:send", "whatsapp:read"],
  "instanceIds": ["inst_xxx"],
  "spendLimitMode": "CREDITS",
  "spendLimitCredits": 50000
}
```

`environment`: **`LIVE`** (producción) o **`SANDBOX`** (prueba).

***

## Scopes de billing

| Scope            | Permite                                             |
| ---------------- | --------------------------------------------------- |
| `billing:read`   | Suscripción, saldo, tarjetas, historial de créditos |
| `billing:manage` | Suscribir/cancelar, recargar, tokenizar tarjetas    |

Rutas: `/v1/platform/workspaces/:id/subscription`, `/balance`, `/payment-methods`, `/credits/usage`.

***

## Scopes de equipo

| Scope                      | Permite                                      |
| -------------------------- | -------------------------------------------- |
| `workspace:members:read`   | Listar miembros e invitaciones pendientes    |
| `workspace:members:manage` | Invitar, cancelar invitación, quitar miembro |

Rutas: `/v1/platform/workspaces/:id/members`, `/invites`.