> For the complete documentation index, see [llms.txt](https://docs.blerify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blerify.com/es/introduccion/authentication.md).
# Autenticación
Esta página te muestra qué es una cuenta de servicio, cómo crear una en el Portal y cómo intercambiar sus credenciales por un token portador que puedes usar en cada solicitud. Todas las llamadas a la API de Blerify funcionan así, ya sea que uses Emisión, Verificación o Registro de confianza.
## Requisitos previos
* Acceso de administrador al [Portal de Blerify](https://portal.blerify.com/)
## Qué es una cuenta de servicio
Una cuenta de servicio no es una persona. Es una identidad que tu backend usa para llamar a la API de Blerify. No tiene nada que ver con ningún inicio de sesión individual, y nunca pasa por un flujo de inicio de sesión humano. Puedes limitar una cuenta de servicio a un solo producto (Emisión o Verificación), o darle roles en varios productos a la vez. Los roles que asignes deciden qué puede hacer realmente la cuenta. Revisa la página de Roles y permisos del Portal de cada producto para ver la lista completa de roles disponibles.
La autenticación funciona mediante la concesión OAuth 2.0 `client_credentials` concesión, usando `private_key_jwt` como método de autenticación del cliente ([RFC 7523](https://www.rfc-editor.org/rfc/rfc7523)). No existe un secreto compartido del cliente. En su lugar, la clave privada de tu cuenta de servicio firma una afirmación JWT de corta duración, y cambias esa afirmación por un token portador.
## Crear una cuenta de servicio
1. Inicia sesión en el [Portal de Blerify](https://portal.blerify.com/) con una cuenta de administrador.
2. Ve a **Configuración → Cuentas de servicio**.
3. Haz clic en **Crear cuenta de servicio**.
4. Completa los detalles de la cuenta:
* **Nombre** — un identificador descriptivo (p. ej., `payments-integration`, `kyc-backend`)
* **Descripción** — opcional; para qué se usa esta cuenta
* **Roles** — los permisos que necesita esta cuenta, delimitados por producto (p. ej., `verifications.api`, `credentials.api`, `notifications.api`)
5. Haz clic en **Create**. El Portal genera un archivo JSON de credenciales y lo descarga de inmediato. **No puedes obtener este archivo de nuevo**, así que guárdalo en un lugar seguro antes de cerrar el cuadro de diálogo.
## El archivo de credenciales
El JSON descargado tiene todo lo que necesitas para autenticarte:
```json
{
"type": "service_account",
"organization_id": "your-organization-id",
"client_id": "your-client-id",
"private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
"token_uri": "https://...",
"iam_audience": "https://..."
}
```
| Campo | Usado para |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id` | Identifica la cuenta de servicio. Se envía como el `client_id` campo de formulario, y también se usa como `iss` y `sub` en la afirmación JWT |
| `organization_id` | Se envía como el `organization_id` campo de formulario |
| `private_key` | Firma la afirmación JWT (RS256) |
| `token_uri` | El endpoint de token al que envías la afirmación. Léelo siempre desde el archivo, ya que puede variar según la cuenta |
| `iam_audience` | El `aud` reclamación en la afirmación JWT |
Mantén el `private_key` secreto. Trata este archivo como una contraseña: no lo commits al control de código fuente, no lo pongas en código del lado del cliente y no lo registres en ningún lugar.
## Obtén un token de acceso
Crea una afirmación JWT de corta duración firmada con tu clave privada, luego envíala a `token_uri`. Todo lo que necesitas ya está en el archivo de credenciales — copia los valores tal como están. Lo único que generas tú mismo son las dos marcas de tiempo y la `jti`.
**Estructura de la afirmación JWT:**
```json
// header
{ "alg": "RS256", "typ": "JWT" }
// payload
{
"iss": "",
"sub": "",
"aud": "",
"iat": 1700000000,
"exp": 1700003600,
"jti": "a-unique-uuid-v4"
}
```
El `jti` necesita ser único en cada solicitud, ya que evita que el token sea reutilizado. Mantén la afirmación de vida corta: una hora es un buen valor predeterminado.
**Solicitud de token:**
```bash
curl -X POST '' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=' \
-d 'organization_id=' \\
-d 'client_afirmación='
```
**Response:**
```json
{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 600
}
```
Leer `expires_in` de la response en lugar de codificar un número de forma fija, ya que puede cambiar.
### Usa una biblioteca en lugar de construir desde cero
El oficial [`blerify/auth-php-client`](https://github.com/BlerifyPlatform/auth-php-client) el paquete maneja la firma de afirmación, el almacenamiento en caché del token y su renovación a partir de un archivo JSON de credenciales. Si trabajas en PHP, empieza por ahí.
## Usa el token
Pon el token en el `Authorization` encabezado de cada solicitud de API:
```
Authorization: Bearer eyJ...
```
Guarda el token en caché y actualízalo antes de que `expires_in` se agote. Si solicitas un token nuevo en cada llamada, agregarás latencia y alcanzarás los límites de tasa bajo carga.
## Próximos pasos
[**Empezar con la emisión**](/es/introduccion-a-la-emision/build/get-started.md): emite tu primera credencial usando una cuenta de servicio con el `credentials.api` rol.
Ver también: [Empezar con la verificación](/es/introduccion-a-la-verificacion/build/get-started.md) · Referencias completas de endpoint en
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.blerify.com/es/introduccion/authentication.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.