Saltar al contenido principal

Autenticación

Todos los endpoints requieren un token, excepto GET /health y GET /errors. El token siempre viaja en el mismo header:

Authorization: Bearer <access_token>

Hay dos formas de conseguirlo. Las dos devuelven un JWT emitido por el servidor de autenticación de Berlinesa; lo que cambia es quién se autentica.

Sesión de usuarioAPI Client
Quién se autenticaUna persona, con usuario y contraseñaTu backend o un agente, sin intervención humana
Cómo se obtieneIniciando sesión en la app web (OIDC)Grant client_credentials contra el token endpoint
Para qué sirveProbar la API y gestionar API ClientsIntegraciones server-to-server
Esquema en la referenciauser-sessionapi-client

Casi todos los endpoints de negocio aceptan cualquiera de los dos. La excepción son los de /api-clients, que exigen siempre una sesión de usuario: un API Client nunca puede crear ni revocar otros API Clients.

Integraciones: usá un API Client​

Para una integración real (tu backend emitiendo facturas), usá un API Client. Es un client OAuth 2.0 propio de tu cuenta, con su client_id y client_secret.

1. Crear el API Client​

Iniciá sesión en la app web de Berlinesa (ver Ambientes) y creá un API Client desde la sección API Clients. También podés crearlo por API con tu token de sesión:

curl -X POST "$API_URL/api-clients" \
  -H "Authorization: Bearer $TOKEN_DE_SESION" \
  -H "Content-Type: application/json" \
  -d '{ "label": "mi-backend" }'

Consultá el body completo y la respuesta en la referencia de POST /api-clients. Guardá el client_id y el client_secret en tu gestor de secretos.

2. Pedir un access token​

No es un endpoint de la API: es el token endpoint estándar de OAuth 2.0 (ver la URL en Ambientes).

curl -X POST "$TOKEN_URL" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET"
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
  "expires_in": 300,
  "token_type": "Bearer",
  "...": "..."
}

Usá access_token como Bearer en cada request. Cuando vence (expires_in, en segundos), pedí uno nuevo con el mismo grant: no hay refresh token en este flujo.

3. Revocar​

DELETE /api-clients/{id} deshabilita el client: no se pueden pedir tokens nuevos y la API responde 401 a los que ya se habían emitido.

Identidad: siempre sale del token​

La API nunca toma un id de usuario de la URL, el body o la query: el usuario sale del token verificado. Por eso no hay endpoints para operar sobre recursos de otro usuario, y GET /users/me siempre devuelve el perfil del dueño del token.

Errores de autenticación​

Todos devuelven 401, con un code distinto según el motivo:

  • falta el header Authorization o no es un Bearer;
  • el token es inválido o está vencido;
  • el token es de un API Client revocado;
  • el token es de un API Client y el endpoint exige una sesión de usuario (/api-clients).

El cuerpo sigue el formato de errores de la API (ver Convenciones) y el listado completo de códigos está en el catálogo de errores.