Get Access Tokens and Permissions

This guide explains how to use the Authorization Window to get short-lived 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 short-lived 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 a short-lived access token.

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

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

Query String Parameters

All parameters except state are required.

Parameter	Sample Value	Description
`client_id` Required Numeric string	`990602627938098`	Your Instagram App ID displayed in App Dashboard > Products > Instagram > Basic Display.
`redirect_uri` Required String	`https://socialsizzle.herokuapp.com/auth/`	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- or space-separated list	`user_profile,user_media`	A comma-separated list, or URL-encoded space-separated list, of 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
  ?client_id=990602627938098
  &redirect_uri=https://socialsizzle.herokuapp.com/auth/
  &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 short-lived Instagram User Access Token.

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

Parameter	Value
`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 short-lived 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.

Parameter	Sample Value	Description
`client_id` Required Numeric string	`990602627938098`	Your Instagram App ID displayed in App Dashboard > Products > Instagram > Basic Display.
`client_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. 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 client_id=990602627938098 \
  -F client_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 short-lived access token and User ID.

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

Capture the access_token value. This is the user’s short-lived 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"
}