Autenticación

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

OAuth 2.0 - Autorización a dos bandas

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:

Combine el clientId y el secreto del cliente: ex. “5:11728663-C8DD-4B84-9B2B-4E3916631A54”
Asegúrese de que "clientId:client-secret" están codificados en Base64.

Añade las credenciales del cliente codificadas a la cabecera de autorización de la solicitud:

Autorización: Basic
NToxMTcyODY2My1DOERELTRCODQtOUIyQi00RTM5MTY2MzFBNTQ=

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:

{
“access_token”:
“tG05IRnPA3hBINzKmIU28zR60xqoachJzI5av5RMTeCRE8uNzeYt95w9XOmNon-4lF3KXQj
gakNfMT9nHgtRxItobmdkZ4xi849LlMhS6SKyCQvHI….”,
“token_type”: “Bearer”,
“expires_in”: 28799,
“refresh_token”:
“898c0a5d1a5c42a9898caf23de67467847db7c42e53f4aa8b599eadc495c55e4”
}

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

Respuesta:

{
“access_token”:”qKDJ5M7LPX-Do3aPCsaIrRzJ1_wsVt_6Whm2dMAkeMYTs1S5uQe…..”,
“token_type”:”Bearer”,
“expires_in”:28799,
“refresh_token”:”b368fd873df3406cb5b35482f68eb1597111ed851cf243df9edeb5e7e52ee4dc”
}

OAuth 2.0 - Autorización de tres patas

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.

http://your/redirect_uri/?error=access_denied&state=partners-unique-value

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:

{
“access_token”:”dfsahjaAsdYza1Rp6VSYwJ5M7LPX-Do3aPCsaIrRzJ1_wsVt_6Whm2d
MAkeMYTs1S5uQe…..”,
“token_type”:”Bearer”,
“expires_in”:28799,
“refresh_token”:”jfdkshfjdhs73df3406cb5b35482f68eb1597111e
d851cf243df9e deb5e7e52ee4dc”
}

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.