Getting Access Tokens and Permissions

This guide explains how to use the Authorization Window to get Instagram User Access Tokens and permissions from Instagram users.

Step 1: Get Authorization

The Authorization Window allows app users to grant your app permissions and Instagram User Access Tokens. After a user logs in and chooses which data to allow your app to access, we will redirect the user to your app and include an Authorization Code, which you can then exchange for an access token.

To begin the process, get the Authorization Window and present it to the user:

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

Query String Parameters

All parameters except state are required.

ParameterSample ValueDescription

app_id
Required
Numeric string

990602627938098

Your Instagram App ID displayed in App Dashboard > Products > Instagram > Basic Display.

redirect_uri
Required
URL-encoded string

https%3A%2F%2Fsocialsizzle. herokuapp.com%2Fauth%2F

A URI where we will redirect users after they allow or deny permission request. Make sure this exactly matches one of the base URIs in your list of valid oAuth URIs. Keep in mind that the App Dashboard may have added a trailing slash to your URIs, so we recommend that you verify by checking the list.

response_type
Required
String

code

Set this value to code.

scope
Required
Comma-separated list

user_profile,user_media

A comma-separated list of login permissions to request from the app user. user_profile is required.

state
String

1

An optional value indicating a server-specific state. For example, you can use this to protect against CSRF issues. We will include this parameter and value when redirecting the user back to you.

Sample Authorization Window URL

https://api.instagram.com/oauth/authorize
  ?app_id=990602627938098
  &redirect_uri=https%3A%2F%2Fsocialsizzle.herokuapp.com%2Fauth%2F
  &scope=user_profile,user_media
  &response_type=code

Successful Authorization

If authorization is successful, we will redirect the user to your redirect_uri and pass you an Authorization Code through the code query string parameter. Capture the code so your app can exchange if for a Instagram User Access Token.

Codes are valid for 1 hour and can only be used once.

Sample Successful Authentication Redirect

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

Note that #_ will be appended to the end of the redirect URI, but it is not part of the code itself, so strip it out.

Canceled Authorization

If the user cancels the authorization flow, we will redirect the user to your redirect_uri and append the following error parameters. It is your responsibility to fail gracefully in these situations and display an appropriate message to your users.

ParameterValue

error

access_denied

error_reason

user_denied

error_description

The+user+denied+your+request

Sample Canceled Authorization Redirect

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

Step 2: Exchange the Code For a Token

Once you receive a code, exchange it for a an access token by sending a POST request to the following endpoint:

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

Body Parameters

Include the following parameters in your POST request body.

ParameterSample ValueDescription

app_id
Required
Numeric string

990602627938098

Your Instagram App ID displayed in App Dashboard > Products > Instagram > Basic Display.

app_secret
Required
String

a1b2C3D4

Your Instagram App Secret displayed in App Dashboard > Products > Instagram > Basic Display.

code
Required
String

AQBx-hBsH3...

The authorization code we passed you in the code parameter when redirecting the user to your redirect_uri.

grant_type
Required
String

authorization_code

Set this value to authorization_code.

redirect_uri
Required
String

https://socialsizzle. heroku.com/auth/

The redirect URI you passed us when you directed the user to our Authorization Window, but without URL-encoding. This must be the same URI or we will reject the request.

Sample Request

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

Sample Success Response

If successful, the API will return a JSON payload containing the app user's access token and User ID.

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

Capture the access_token value. This is the user’s Instagram User Access Token which your app can use to access Instagram Basic Display API endpoints.

Sample Rejected Response

If the request is malformed in some way, the API will return an error.

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