Skip to main content

OAuth

En esta guía te vamos a explicar los pasos que debes seguir para poder integrar el protocolo OAuth en tu plataforma para ofrecer a tus usuarios vincular su cuenta de autosign en tu plataforma

Glosario​

  • Client Application ID: Identificador único de tu plataforma/aplicación dentro de autosign.
  • Scopes: Los recursos del usuario a los cuales quieres tener acceso.
  • Authorization Code: El código generado luego de que el usuario haya dado el consentimiento de querer conectarse con tu plataforma.

Scopes​

Los scopes que puedes utilizar en tu integración son:

  • transaction:read: Otorgar acceso para poder ver las transacciones según tu alcance
  • transaction:create: Otorgar acceso para poder crear transacciones a tu nombre
  • transaction:update: Otorgar acceso para actualiza transacciones creadas
  • webhook:read: Otorgar acceso para poder leer los webhooks creados en tu empresa
  • webhook:create: Otorgar acceso para poder crear webhooks
  • webhook:remove: Otorgar acceso para poder eliminar los webhooks de tu empresa
  • file:create: Otorgar acceso para poder subir archivos (documentos, pdf, etc)
  • template:read: Otorgar acceso para poder ver las plantillas según tu alcance

Al momento de incluir multiples scopes en el link de autorización, deben estar separados con un espacio

Authorization Code Flow​

Un usuario de autosign se conecta a tu plataforma pasando por los siguientes pasos:

  1. Desde una página en tu plataforma, el usuario hace click en un link que lo redirecciona a Autosign Dashboard. Dicho link tiene que tener en sus parámetros el Client Application ID y los Scopes a los que tu plataforma desea acceder.
  2. En Autosign Dashboard, el usuario dará el consentimiento necesario para conectarse con tu plataforma.
  3. El usuario es redireccionado a tu plataforma con un Authorization Code en los parámetros de la URL.
  4. Tu plataforma realiza el intercambio del Authorization Code por un Access Token válido.

1. Crear una aplicación OAuth​

Para empezar con tu integración, dirígete al panel OAuth en configuraciones OAuth 2.0

1. En la sección de OAuth Aplicaciones haz click sobre el botón: Crear aplicacion
2. Rellena el formulario con la información necesaria y envía el formulario
3. Haz click sobre ver credenciales en la aplicacion recientemente creada
4. Obtendrás el Client Application ID y el Client Secret. Tenlo a mano para poder construir el Authorization Link.

Con los dos pasos realizados anteriormente, ya te encuentras listo para crear el Authorization Link.

https://dashboard.autosign.io/oauth/authorize?client_id=clsqvh10i0001tyzkifq3s7xc&scopes=webhook:create%20transaction:create

Este endpoint debe recibir dos parámetros:

  • Tu client_id generado al crear la OAuth application.
  • Los scopes a los cuales deseas acceder.

2. Un usuario conecta su cuenta​

Luego de que el cliente hace click al Authorization Link, será redireccionado a la página de autosign en donde se le preguntará si quiere conectar con tu plataforma.

El proceso de crear una cuenta en autosign o ingresar en la plataforma es responsabilidad nuestra, no debes preocuparte por eso. Todo viene incluído dentro del Authorization Code Flow.

3. El usuario es redirigido a tu plataforma​

Luego de que el cliente haya otorgado los permisos para conectar su cuenta en tu plataforma, será redirigido a la página de tu aplicación que corresponda al link de Callback URL configurado al crear la OAuth Application.

Para culminar con éxito la conexión, nosotros te pasamos en el Callback URL:

  • El Authorization Code (code en los parámetros) para intercambiar por un Access Token. Tiene una expiración de 10 minutos y es de único uso.
https://your-callback-url/auth?code=7ba2af4264226f464f9a199861e49dbd

4. La plataforma completa el flujo​

Intercambia el código recibido por un Access Token.

curl -X POST 'https://api.autosign.io/v1/oauth/exchange/code' \
-H 'Content-Type: application/json' \
-d '{
        "code": "93ea05f364cb4bf0781e3f1864d7190880ccaeea51181c98fefab3a5c0981919",
        "client_secret": "5fc468a5e3dcea7ac731e5786c67e85ce27697c5d7a800f76fd6c839ce19998c",
        "client_id": "clsqvh10i0001tyzkifq3s7xc",
    }'
RESPONSE
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expires_in": 4324324
}

Listo! El usuario ya se encuentra conectado a tu plataforma. Guarda en tu base de datos el access_token. Este token te servirá para autenticarte en las request que realices a autosign API. Para poder hacerlo, sólo debes pasar en el header de la request:Authorization: Bearer $access_token

El refresh_token puede usarse para generar nuevos access_token cuando el actual haya expirado. Te recomendamos que también guardes este tipo de token ya que sólo se generará una única vez cuando realices el exchange del código por el access_token.

Refrescar un Access Token​

Si necesitas refrescar un access_token porque el que tienes expiró, puedes hacerlo pasando a autosign API el refresh_token generado anteriormente:

curl -X POST 'https://api.autosign.io/v1/oauth/refresh/token' \
-H 'Content-Type: application/json' \
-d '{
        "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
        "client_secret": "5fc468a5e3dcea7ac731e5786c67e85ce27697c5d7a800f76fd6c839ce19998c",
        "client_id": "clsqvh10i0001tyzkifq3s7xc",
    }'