El primer paso para integrarse con la API STACK es comprender el proceso de autorización de la API. Cada vez que un socio realiza una solicitud a la API STACK , ya sea en nombre del socio o en nombre de un usuario afiliado a un socio, debe ser autorizado a través del servidor de autorización de STACK.
OAuth 2.0 - Autorización de dos patas
OAuth 2.0 - Autorización de tres patas
Expiración del token
La autorización de dos piernas se utiliza cuando su integración está escribiendo datos en o leyendo de una cuenta que usted controla. Por lo general, se trata de una comunicación de servidor a servidor en la que puede crear proyectos, planes y archivos directamente en su propia cuenta.
Obtención de credenciales de cliente
STACK proporcionará a un socio su propio ClientId y ClientSecret, que juntos constituyen las credenciales de la API. El clientId y el secreto de cliente se combinan, se separan con dos puntos y se codifican en base64 de la siguiente manera:
Añade las credenciales del cliente codificadas a la cabecera de autorización de la solicitud:
Obtención de un token de acceso en nombre del socio
To obtain an access_token, a Partner must make a POST request to this endpoint: “https://{server}/OAuth/Token” and include the Client Credentials in the Authorization header of the request. Replace {server} with the sandbox server URL provided along with your API credentials. A Grant Type is also required in the body of the request; “grant_type=client_credentials”.
Petición:
POST https://{server}/OAuth/Token
Authorization: Basic
VEhJUyBJUyBCQVNFNjQgU1RSSU5HIE9GIFlPVVIgUEFSVE5FUklEfFBBUlRORVIgU0VDUkVU
Cg==
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
Tenga en cuenta que no debe haber finales de línea después de los datos del formulario, si no se devolverá un grant_type inválido. Esto incluye retornos de carro (0x0d) y/o caracteres de nueva línea (0x0a).
Respuesta:
Observe el access_token en la respuesta. El access_token se utilizará en el encabezado de autorización del portador de cualquier solicitud futura a la API. Los access_tokens caducarán como se indica en el campo expires_in de la respuesta y deberán actualizarse utilizando el refresh_token.
Detalles del campo:
Nombre del campo | Tipo | Longitud | Propósito |
código_de_acceso | cadena | 2048 | El access_token se utilizará en el encabezado de autorización del portador de cualquier solicitud futura a la API. Los access_tokens caducarán como se indica en el campo expires_in de la respuesta y deberán actualizarse utilizando el refresh_token. La longitud del campo puede variar con el tiempo, por lo que experimentará cadenas de alrededor de 1030 bytes, pero asegúrese de reservar 2048 bytes en cualquier columna de tabla en la que lo almacene. |
tipo_token | cadena | Siempre "Portador" indicando que así es como se va a utilizar esta ficha. | |
caduca_en | int | El número de segundos de validez de este token. | |
refresh_token | cadena | Después de expires_in segundos este refresh_token se puede utilizar en otra llamada a la API para recuperar otro access_token. |
Autenticación de solicitudes a la API
A continuación se muestra un ejemplo de POST para crear un proyecto utilizando la API de STACK:
Cabeceras de solicitud:
POST https://{server}/api/v1/Projects HTTP/1.1
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
…
Consulte el documento de referencia de la API para obtener información detallada sobre las solicitudes.
Actualización de los tokens de acceso
Como se ha mencionado anteriormente, será necesario actualizar los access_tokens. El proceso es similar a la obtención inicial de un access_token. Utilice sus credenciales de cliente en el encabezado Authorization y formatee su refresh_token como se muestra en el siguiente ejemplo.
Encabezado de la solicitud:
POST https:// {server}.net/OAuth/Token HTTP/1.1
Authorization: Basic (your Client Credentials)
Content-Type: application/x-www-form-urlencoded
refresh_token=d826c4204c847bf63a16d271adea23e…&grant_type=refresh_token
Tenga en cuenta que no debe haber finales de línea después de los datos del formulario, si no se devolverá un grant_type inválido. Esto incluye retornos de carro (0x0d) y/o caracteres de nueva línea (0x0a).
Respuesta:
{
“access_token”:”qKDJ5M7LPX-Do3aPCsaIrRzJ1_wsVt_6Whm2dMAkeMYTs1S5uQe…..”,
“token_type”:”Bearer”,
“expires_in”:28799,
“refresh_token”:”b368fd873df3406cb5b35482f68eb1597111ed851cf243df9edeb5e7e52ee4dc”
}
La autorización de tres patas se utiliza cuando tu integración está escribiendo o leyendo datos de una cuenta en nombre de un usuario. Esto requiere que el usuario conceda a tu integración permiso para controlar sus datos. Su aplicación solicitará controlar la cuenta de un usuario y éste deberá hacer clic en un botón para conceder a su aplicación los permisos adecuados.
Obtener autenticación en nombre del usuario
A continuación describiremos cómo autorizar el acceso a la API en nombre de un usuario. La idea es que uno de sus clientes está interactuando con su producto y desea transferirlo a STACK. Usted ya tendrá un token de acceso desde el flujo de trabajo de dos patas anterior, por lo que ahora tiene que obtener acceso para su usuario.
En primer lugar, el usuario debe ser redirigido a la página de autorización de STACK. Esto puede lograrse mediante una url de redirección aplicada a una acción iniciada por el usuario, como hacer clic en un enlace de la página del socio para ver un proyecto en la aplicación STACK . La redirección contendrá la redirect_uri proporcionada por el socio y el ClientID proporcionado por STACK:
Petición:
https://{server}/OAuth/Authorize?client_id=(your
ClientId)&redirect_uri=(your redirect_uri
encoded)&state=partner-created-value&response_type=code
El ClientID es el ID que STACK le proporcionó para sus Credenciales de Cliente.
La redirect_uri es la uri que ha proporcionado a STACK y se guarda en la base de datos de STACKcomo parte de su información de socio. Cuando se envía en la cadena de consulta, la uri debe estar codificada.
Ejemplo:
http%3A%2F%2Fyour%2Fredirect_uri.com
El parámetro de estado es generado por el Socio para uso del Socio.
La parte response_type=code de la cadena de consulta indica al Servidor de Autorización STACK que está solicitando un código de un solo uso (GUID generado por el Servidor de Autorización) que se utilizará para obtener un access_token para su Usuario.
Este es un ejemplo de lo que el usuario verá generado por el Servidor de Autorización STACK
Una vez que el usuario concede el acceso al socio haciendo clic en el botón "Conceder", el usuario será redirigido a la redirect_uri del socio y el código de un solo uso se especificará en la cadena de consulta. La cadena de consulta devuelta debe parecerse al ejemplo siguiente:
Ejemplo:
http://your/redirect_uri/?code=7d07711d50c14cfeb0759d262878b03b37c50b063
5614ee8893a166e526da90b&state=partner-created-value
Tenga en cuenta que el parámetro de estado devuelto es el mismo valor que se pasó a STACK en la solicitud original. El código proporcionado es de corta duración y está configurado para expirar en 5 minutos. Si el usuario opta por hacer clic en el botón Cancelar, se producirá una redirección similar de vuelta a la redirect_uri del socio con un argumento de cadena de consulta de error que indica el acceso denegado.
El cliente espera que se le presente la misma página de socio que utilizó para iniciar STACK. La solicitud para obtener un access_token para un usuario específico puede realizarse desde el servidor y no requiere ninguna acción adicional por parte del usuario. La solicitud para obtener un access_token para el usuario es similar a la solicitud para obtener un access_token para un socio.
Petición:
POST https://{server}/OAuth/Token HTTP/1.1
Authorization: Basic
VEhJUyBJUyBCQVNFNjQgU1RSSU5HIE9GIFlPVVIgUEFSVE5FUklEfFBBUlRORVIgU0VDUkVU
Cg==
Content-Type: application/x-www-form-urlencoded
code=7d07711d50c14cfeb0759d262878b03b37c5&state=partner-created-value&re
direct_uri=(your redirect_uri)&grant_type=authorization_code
Tenga en cuenta que no debe haber finales de línea después de los datos del formulario, o se devolverá un grant_type inválido. Esto incluye retornos de carro (0x0d) y/o caracteres de nueva línea (0x0a).
Respuesta:
Observe el access_token en la respuesta. El access_token se utilizará en el encabezado de autorización del portador de cualquier solicitud futura a la API. Los access_tokens caducarán como se indica en el campo expires_in de la respuesta y deberán actualizarse utilizando el refresh_token.
Expiración del token
El código de autorización, el token de acceso y el token de actualización caducan en diferentes momentos. En la tabla siguiente se explican los ajustes que debe gestionar:
Tipo de ficha | Hora de expiración | Razón |
Código de autorización | 5 minutos | Se trata de un valor efímero, que se transmite al interlocutor para su uso inmediato con el fin de recuperar un testigo de acceso. |
Clave de acceso | 8 horas | Un token de acceso, para autenticación a dos o tres bandas, representa únicamente una sesión iniciada y se actualiza periódicamente para garantizar que el estado de la credencial no ha cambiado. |
Actualizar ficha | 90 días | Este largo periodo de tiempo representa que el permiso concedido a los usuarios se verifica con una frecuencia constante. |