Skip to main content

OAuth 2.0

Cuando usar OAuth 2.0​

Te recomendamos esta implementación cuando los usuarios de tu plataforma tienen contratado Autoinspector y vos unicamente actúas como intermediario para realizar consumos sobre la API con la identidad de otro usuario

Cuando NO usar OAuth 2.0​

No te recomendamos esta implementación cuando tu empresa o plataforma puede consumir Autoinspector API directamente mediante el uso de API Keys, principalmente para evitar el costo de administrar tokens de corta vida

Glosario​

  • Client Application ID: Identificador único de tu plataforma/aplicación dentro de Autoinspector.
  • 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 recursos de un usuario a los cuales puedes acceder son:

  • memberships: Te permite acceder a la información de cuáles son las empresas a la que el usuario pertenece.
  • account: Te permite acceder a la información pública del usuario.
  • inspections: Te permite acceder a la información de las inspecciones y la habilidad de crear una de ellas.

Authorization Code Flow​

Un usuario de Autoinspector 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 Autoinspector 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 Autoinspector 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 a Developer Settings

1. En la sección de OAuth Aplicaciones haz click sobre el botón: Crear una aplicación
2. Rellena el formulario con la información necesaria y envía el formulario
3. 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.autoinspector.ai/oauth/connect?client_app_id=61f57567e3be53561a89e7ce&scopes=inspections&scopes=memberships

Este endpoint debe recibir dos parámetros:

  • Tu client_app_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 Autoinspector en donde se le preguntará si quiere conectar con tu plataforma.

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

Si el usuario ya se encuentra logueado, le aparecerá directamente la página de consentimiento

Si el usuario no tiene una cuenta, deberá registrarse.

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.

const Autoinspector = require('autoinspector')

const autoinspector = new Autoinspector({
  apikey: 'YOUR_API_KEY',
})

const accessToken = await autoinspector.oauth.exchangeCodeForAccessToken(
  'THE_CODE_RECEIVED_IN_PARAMS',
)
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 Autoinspector 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 Autoinspector API el refresh_token generado anteriormente:

const Autoinspector = require('autoinspector')

const autoinspector = new Autoinspector({
  apikey: 'YOUR_API_KEY',
})

const accessToken = await autoinspector.oauth.refreshAccessToken(
  'YOUR_REFRESH_TOKEN',
)

Samples​

Puedes encontrar un ejemplo de cómo realizar toda esta implementación desde cero.