# Autenticación

> Cómo autenticarte en la API de Blogenia con una clave pk_live_ en la cabecera Authorization.

Versión web: https://blogelia.com/docs/autenticacion

Todas las peticiones llevan una clave de API en la cabecera `Authorization`, con el esquema `Bearer`.

**Cabecera**

```http
Authorization: Bearer pk_live_0123456789abcdef0123456789abcdef
```

## La clave

- Formato: `pk_live_` seguido de 32 caracteres hexadecimales.
- Se crea en el [panel](https://app.blogelia.com/api), en **API**. Solo se muestra al crearla. Blogenia guarda únicamente su huella (SHA-256).
- Puedes tener hasta 10 claves activas. Al revocar una, deja de funcionar al momento en el proceso que la revoca y, como máximo, 30 segundos después en el resto.
- Cada clave pertenece a tu organización y solo ve sus datos.
- Las claves son de solo lectura y llevan **permisos** (scopes) que eliges al crearlas. Ver [Permisos](#scopes).

## Permisos (scopes)

Cada clave lleva solo los permisos que necesita, para que una clave filtrada dé el menor acceso posible. Se marcan al crear la clave en el [panel](https://app.blogelia.com/api) y, si no marcas ninguno, la clave lleva solo `content:read`.

| Permiso | Qué permite | Rutas |
| --- | --- | --- |
| `content:read` | Leer el contenido publicado. | `GET /blogs/{blogId}`, `GET /blogs/{blogId}/articles` y `GET /articles/{id}`. Ver [Blogs](https://blogelia.com/docs/blogs) y [Artículos](https://blogelia.com/docs/articulos). |
| `stats:read` | Leer la analítica de visitas. | `GET /account/stats`, `GET /blogs/{blogId}/stats`, `GET /blogs/{blogId}/stats/articles` y `GET /articles/{id}/stats`. Ver [Analítica](https://blogelia.com/docs/analitica). |
| `account:read` | Leer datos internos de la cuenta: créditos, plan, artículos en cualquier estado, generaciones, piloto automático y entregas. | [Cuenta](https://blogelia.com/docs/cuenta), [Artículos (todos los estados)](https://blogelia.com/docs/articulos-todos), [Generaciones](https://blogelia.com/docs/generaciones), [Piloto automático](https://blogelia.com/docs/piloto-automatico) y [Entregas](https://blogelia.com/docs/entregas). |

- Las claves anteriores con el permiso `read` cuentan como `content:read`: siguen funcionando igual y no ganan permisos nuevos.
- Si la clave no tiene el permiso de la ruta, la respuesta es `403` con `code: "insufficient_scope"` y el permiso que falta en el mensaje.
- **Los permisos no se pueden cambiar después de crear la clave.** Para ampliarlos, crea otra clave y revoca la antigua (como al [rotar](https://blogelia.com/docs/seguridad#rotar) una clave). Así una clave filtrada nunca gana permisos.
- `account:read` solo puede concederlo el propietario de la cuenta; si no lo eres, la creación responde `403` con `code: "owner_required"`. El panel avisa de que da acceso a datos internos y que no debe usarse en el navegador.
- Todos los permisos comparten el [límite de uso](https://blogelia.com/docs/limites) de la clave.
- Las rutas de `stats:read` y `account:read` no admiten CORS: solo se pueden llamar desde un servidor.

> **Nota:** La clave y sus permisos se crean desde el panel (**API**), no con una petición a la API: crear una clave exige iniciar sesión, no se hace con otra clave.

## Dónde vale

Una clave solo funciona en las rutas `GET` de esta documentación, y cada una con su permiso: las de lectura de contenido ([Blogs](https://blogelia.com/docs/blogs) y [Artículos](https://blogelia.com/docs/articulos)), las de [Analítica](https://blogelia.com/docs/analitica) y las de cuenta ([Cuenta](https://blogelia.com/docs/cuenta), [Artículos (todos los estados)](https://blogelia.com/docs/articulos-todos), [Generaciones](https://blogelia.com/docs/generaciones), [Piloto automático](https://blogelia.com/docs/piloto-automatico) y [Entregas](https://blogelia.com/docs/entregas)). En cualquier otra ruta, la respuesta es `401` con el mensaje «Esta ruta no admite claves de API».

## Si la autenticación falla

| Respuesta | Cuándo |
| --- | --- |
| `401` «Falta el token de acceso» | No hay cabecera `Authorization: Bearer …`. |
| `401` «Clave de API no válida» | La clave no existe, está revocada o no tiene el formato `pk_live_` + 32 hexadecimales. |
| `403` `plan_required` | Tu organización está en el plan Free. |
| `403` `ORGANIZATION_SUSPENDED` | Tu organización está suspendida. |
| `403` `insufficient_scope` | La clave es válida pero no tiene el permiso de la ruta. Ver [Permisos](#scopes). |

## No uses la clave en el navegador

Las tres rutas de lectura de contenido aceptan peticiones desde cualquier origen (CORS) pero sin cookies ni credenciales. Aun así, cualquiera que abra tu web podría leer la clave. Haz la petición desde tu servidor y entrega el resultado al navegador. Más consejos en [Seguridad](https://blogelia.com/docs/seguridad).

### CORS

- Solo `GET` y `HEAD` en las tres rutas de lectura de contenido (`content:read`), desde cualquier `Origin`, sin credenciales. Las rutas de `stats:read` y `account:read` no llevan CORS.
- Cabeceras expuestas al navegador: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` y `Retry-After`.