Este documento foi atualizado.
A tradução para Português (Brasil) não foi concluída ainda.

Atualização em inglês: 13 de out de 2021

Obter tokens de acesso e permissões

Este guia explica como usar a janela de autorização para obter tokens de acesso do usuário do Instagram de curta duração e permissões de usuários do Instagram.

Etapa 1: obter autorização

A janela de autorização permite que usuários concedam ao seu aplicativo permissões e tokens de acesso do usuário do Instagram de curta duração. Depois de fazer o login e escolher os dados aos quais o aplicativo terá acesso, o usuário é redirecionado ao aplicativo, e incluímos um código de autorização, que você pode trocar por um token de acesso de curta duração.

Para dar início ao processo, obtenha a "janela de autorização" e a forneça ao usuário:

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 da string de consulta

Todos os parâmetros, exceto state, são obrigatórios.

Parâmetro	Exemplo de valor	Descrição
`client_id` Obrigatório String numérica	`990602627938098`	ID do aplicativo do Instagram exibido em Painel de Aplicativos > Produtos > Instagram > Exibição básica.
`redirect_uri` Obrigatório String	`https://socialsizzle.herokuapp.com/auth/`	Um URI para onde serão redirecionados os usuários depois que a solicitação de permissão for autorizada ou negada. Verifique se ele corresponde exatamente aos URIs básicos em sua lista de URIs do OAuth válidos. Tenha em mente que o Painel de Aplicativos pode adicionar uma barra à direita no final dos seus URIs. Por isso, é recomendado consultar a lista para fins de verificação.
`response_type` Obrigatório String	`code`	Configure esse valor para `code`.
`scope` Obrigatório Lista separada por vírgulas ou espaços	`user_profile,user_media`	Uma lista separada por vírgulas ou uma lista separada por espaços em formato URL das permissões a serem solicitadas do usuário do aplicativo. O `user_profile` é obrigatório.
`state` String	`1`	Um valor opcional que indica um estado específico do servidor. Por exemplo, use isso para se proteger de problemas relacionados a CSRF. Incluiremos esse parâmetro e o valor correspondente ao redirecionar o usuário de volta para você.

Exemplo de URL de janela de autorização

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

Autorização bem-sucedida

Caso a autorização seja bem-sucedida, o usuário será redirecionado a seu redirect_uri e você receberá um código de autorização por meio do parâmetro da string de consulta code. Capture o código para que o aplicativo possa trocá-lo por um token de acesso do usuário do Instagram de curta duração.

Os códigos de autorização têm validade de uma hora e só podem ser usados uma vez.

Exemplo de redirecionamento de autenticação bem-sucedido

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

Observe que #_ será anexado ao final do URI de redirecionamento, mas não faz parte do código em si e deve ser excluído.

Autorização cancelada

Caso o usuário cancele o fluxo de autorização, ele será redirecionado para seu redirect_uri, e os seguintes parâmetros de erro serão anexados. Em caso de falha, é sua responsabilidade reconhecer o erro e exibir uma mensagem adequada para os usuários.

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

Exemplo de redirecionamento de autenticação cancelado

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

Etapa 2: trocar o código por um token

Depois de receber o código, troque-o por um token de acesso de curta duração enviando uma solicitação POST para o seguinte ponto de extremidade:

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

Parâmetros de corpo

Inclua os seguintes parâmetros no corpo da solicitação POST.

Parâmetro	Exemplo de valor	Descrição
`client_id` Obrigatório String numérica	`990602627938098`	ID do aplicativo do Instagram exibido em Painel de Aplicativos > Produtos > Instagram > Exibição básica.
`client_secret` Obrigatório String	`a1b2C3D4`	A chave secreta do aplicativo do Instagram exibida em Painel de Aplicativos > Produtos > Instagram > Exibição básica.
`code` Obrigatório String	`AQBx-hBsH3...`	O código de autorização que você recebeu no parâmetro `code` quando redirecionamos o usuário ao `redirect_uri`.
`grant_type` Obrigatório String	`authorization_code`	Configure esse valor para `authorization_code`.
`redirect_uri` Obrigatório String	`https://socialsizzle. heroku.com/auth/`	O URI de redirecionamento que você informou ao direcionar o usuário à janela de autorização. O URI deve ser o mesmo, caso contrário, a solicitação será rejeitada.

Exemplo de solicitação

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...

Exemplo de resposta de sucesso

Em caso de sucesso, a API retornará uma carga JSON contendo o token de acesso de curta duração do usuário do aplicativo e o número de identificação do usuário.

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

Capture o valor access_token. Esse é o token de acesso do usuário do Instagram de curta duração que o aplicativo usará para acessar os pontos de extremidade da API de Exibição básica do Instagram.

Exemplo de resposta rejeitada

Caso a solicitação apresente alguma irregularidade, a API retornará um erro.

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