Autenticación y Tokens de Acceso
Introducción
El manejo eficaz de tokens es clave para lograr interacciones seguras y eficientes con las APIs. La API de Passport utiliza el modelo de autenticación OAuth2, lo que garantiza un esquema seguro para autenticar y autorizar solicitudes. Esta guía presenta una visión estructurada sobre cómo generar, administrar y revocar tokens de acceso.
Autenticación tipo Bearer
La autenticación Bearer (o autenticación por token) es un esquema HTTP que utiliza tokens de seguridad. La lógica es sencilla: quien porta el token (Bearer) tiene acceso.
Los tokens Bearer son cadenas largas y aleatorias generadas por el servidor tras una solicitud de autorización exitosa. Una vez obtenido el token, debe incluirse en el encabezado Authorization al realizar solicitudes a endpoints protegidos:
Authorization: Bearer <token>Flujo de Autenticación
- Registrar la Entidad: Primero debes registrarte en la plataforma Passport.
- Obtener las Credenciales de API: Después de registrarte, puedes encontrar tu
Client ID(API Key) yClient Secret(API Secret) en el tablero de control, en la sección Plataforma > Claves API. - Generar un Token de Acceso: Con estas credenciales podrás solicitar un token de acceso para realizar llamadas a la API.
Endpoints para gestión de tokens
Generar un Token de Acceso
| Definición | Descripción |
|---|---|
| Endpoint | https://api.paas.sandbox.co.passportfintech.com/v1/iam/oauth/tokens |
| Método | POST |
| Encabezados | Accept-Language, Content-Length, Content-Type: application/json |
| Autenticación | Client Credentials (API Key y API Secret) |
Parámetros del Cuerpo de la Solicitud
| Parámetro | Tipo | Descripción |
|---|---|---|
| client_id | String | Tu API Key (Client ID) generado al registrarte. |
| client_secret | String | Tu API Secret (Client Secret) correspondiente. |
| grant_type | String | Debe ser client_credentials. |
Ejemplo de Solicitud
{ "client_id": "TU_API_KEY", "client_secret": "TU_API_SECRET", "grant_type": "client_credentials"}
Creación de Token de Acceso
Ejemplo de respuesta
Una solicitud exitosa devuelve un código HTTP 200 OK con el siguiente cuerpo:
{ "token": { "scopes": [ "iam.oauth.tokens.delete", "iam.users.roles.list.get", "paas.core.breb_recipients.post", "paas.core.entity_customers.list.get", "iam.roles.list.get", "paas.core.accounts.list.get", "iam.oauth.tokens.list.get", "paas.core.breb_payments.list.get", "iam.roles.get", "iam.logout.post", "paas.core.entity_customers.patch", "paas.core.breb_payments.get", "iam.users.get", "paas.core.account_keys.list.get", "iam.roles.users.list.get", "paas.core.account_keys.post", "iam.mfa.*", "paas.core.entity_customers.get", "iam.users.list.get", "paas.core.accounts.post", "iam.login_profiles.patch", "paas.core.breb_payments.post", "paas.core.account_keys.get", "paas.core.breb_recipients.list.get", "paas.core.entity_customers.post", "paas.core.accounts.get", "iam.accounts.get", "iam.oauth.tokens.get", "paas.core.breb_recipients.get" ], "created_at": "2025-03-04T19:38:55.942Z", "token_type": "Bearer", "access_token": "a84d6431ee878a9d0b483844a1ec9e18bb2d8c52343bf1699a56876f6f7aed46", "expires_in": 86400, "token_id": "f029629f-2383-40fe-9597-401b38e32408", "roles": [ "entity.admin" ] }, "id": "208c6a13-b9e1-473f-b014-03d4e57bbe38"}El token de acceso tiene una validez de 24 horas (86,400 segundos).
Buenas prácticas para el manejo de tokens
- Usa tokens de corta duración: Renuévalos periódicamente para mayor seguridad.
- Almacena credenciales de forma segura: Nunca expongas claves o tokens en código del lado del cliente.
- Rota las API Keys regularmente: para prevenir accesos no autorizados.
Próximos Pasos
Ya que comprendes cómo generar y gestionar tokens de acceso en Passport, puedes continuar con:
- Integrar tus credenciales en Postman o tu sistema de desarrollo.
- Usar el token generado para autenticar llamadas a los distintos endpoints de la plataforma.
- Explorar los flujos disponibles en nuestra colección de Postman y documentación detallada por endpoint.