Se actualizó este documento.
La traducción en español no está disponible todavía.

Actualización del documento en inglés: 8 nov. 2021

Obtener tokens de acceso y permisos

En esta guía se explica cómo usar la ventana de autorización para obtener tokens de acceso de usuarios de Instagram y permisos de corta duración de usuarios de Instagram.

Paso 1: Obtener autorización

La ventana de autorización permite que los usuarios de la app otorguen a esta permisos y tokens de acceso de usuarios de Instagram de corta duración. Después de que un usuario inicie sesión y elija los datos a los que tu app tendrá acceso, lo redireccionaremos nuevamente a la app e incluiremos un código de autorización que luego podrás cambiar por un token de acceso de corta duración.

Para iniciar el proceso, accede a la ventana de autorización y preséntala al usuario:

https://api.instagram.com/oauth/authorize
  ?client_id={instagram-app-id}
  &redirect_uri={redirect-uri}
  &scope={scope}
  &response_type=code
  &state={state}        //Optional

Parámetros de la cadena de la consulta

Todos los parámetros son obligatorios, con excepción de state.

Parámetro	Valor de ejemplo	Descripción
`client_id` Obligatorio Cadena numérica	`990602627938098`	El identificador de la app de Instagram, que se muestra en Panel de apps > Productos > Instagram > Visualización básica.
`redirect_uri` Obligatorio Cadena	`https://socialsizzle.herokuapp.com/auth/`	Un URI al que redireccionaremos a los usuarios después de que acepten o rechacen la solicitud de permiso. Asegúrate de que coincida exactamente con uno de los URI base de tu lista de URI oAuth válidos. Ten en cuenta que el panel de apps puede haber agregado una barra final a los URI, por lo que te recomendamos que compruebes la lista.
`response_type` Obligatorio Cadena	`code`	Configura este parámetro con el valor `code`.
`scope` Obligatorio Lista separada por comas o espacios	`user_profile,user_media`	Una lista separada por comas (o separada por espacios y con URL cifrada) de los permisos que se deben solicitar al usuario de la app. `user_profile` es obligatorio.
`state` Cadena	`1`	Valor opcional que indica un estado específico del servidor. Por ejemplo, puedes utilizarlo para protegerte contra la falsificación de solicitudes entre sitios (CSRF). Incluiremos este parámetro y este valor al volver a redireccionar al usuario a tu app.

Ejemplo de URL de la ventana de autorización

https://api.instagram.com/oauth/authorize
  ?client_id=990602627938098
  &redirect_uri=https://socialsizzle.herokuapp.com/auth/
  &scope=user_profile,user_media
  &response_type=code

Autorización correcta

Si la autorización se realiza correctamente, redireccionaremos al usuario a tu redirect_uri y te enviaremos un código de autorización a través del parámetro de cadena de consulta code. Captura el código para poder cambiarlo por un token de acceso de usuario de Instagram de corta duración.

Los códigos son válidos durante 1 hora y se pueden usar solo una vez.

Ejemplo de un redireccionamiento de autenticación exitoso

https://socialsizzle.herokuapp.com/auth/?code=AQBx-hBsH3...#_

Ten en cuenta que #_ se agregará al final del URI de redireccionamiento, pero no forma parte del código, así que elimínalo.

Autorización cancelada

Si el usuario cancela el proceso de autorización, lo redireccionaremos a tu redirect_uri y agregaremos los siguientes parámetros de error. En estas situaciones, es tu responsabilidad actuar con corrección y mostrar un mensaje apropiado a tus usuarios.

Parámetro	Valor
`error`	`access_denied`
`error_reason`	`user_denied`
`error_description`	`The+user+denied+your+request`

Ejemplo de un redireccionamiento de autenticación cancelado

https://socialsizzle.herokuapp.com/auth/?error=access_denied
  &error_reason=user_denied
  &error_description=The+user+denied+your+request

Paso 2: Cambiar el código por un token

Una vez que recibas un código, cámbialo por un token de acceso de corta duración enviando una solicitud POST al siguiente punto de conexión:

POST https://api.instagram.com/oauth/access_token

Parámetros del cuerpo

Incluye los siguientes parámetros en el cuerpo de tu solicitud POST.

Parámetro	Valor de ejemplo	Descripción
`client_id` Obligatorio Cadena numérica	`990602627938098`	El identificador de la app de Instagram, que se muestra en Panel de apps > Productos > Instagram > Visualización básica.
`client_secret` Obligatorio Cadena	`a1b2C3D4`	Clave secreta de tu app de Instagram, que se muestra en Panel de apps > Productos > Instagram > Visualización básica.
`code` Obligatorio Cadena	`AQBx-hBsH3...`	El código de autorización que te enviamos en el parámetro `code` al redireccionar al usuario a tu `redirect_uri`.
`grant_type` Obligatorio Cadena	`authorization_code`	Configura este valor como `authorization_code`.
`redirect_uri` Obligatorio Cadena	`https://socialsizzle. heroku.com/auth/`	El URI de redireccionamiento que nos enviaste cuando dirigiste al usuario a tu ventana de autorización. Debe ser el mismo URI; si no lo es, rechazaremos la solicitud.

Ejemplo de solicitud

curl -X POST \
  https://api.instagram.com/oauth/access_token \
  -F client_id=990602627938098 \
  -F client_secret=eb8c7... \
  -F grant_type=authorization_code \
  -F redirect_uri=https://socialsizzle.herokuapp.com/auth/ \
  -F code=AQBx-hBsH3...

Ejemplo de respuesta correcta

Si el proceso es correcto, la API devolverá una carga JSON que contendrá el token de acceso de corta duración y el ID del usuario de la app.

{
  "access_token": "IGQVJ...",
  "user_id": 17841405793187218
}

Captura el valor access_token. Este es el token de acceso de corta duración del usuario de Instagram que tu app puede usar para acceder a puntos de conexión de la API de visualización básica de Instagram.

Ejemplo de respuesta rechazada

Si la solicitud tiene algún error de formato, la API devolverá un error.

{
  "error_type": "OAuthException",
  "code": 400,
  "error_message": "Matching code was not found or was already used"
}