Get Started

This tutorial shows you how to configure an app in the App Dashboard, get a short-lived Instagram User Access Token, then use the token to query the API for an Instagram user’s profile. When you complete the tutorial you will have a basic understanding of how to get access tokens and permissions from your app users, and how to perform basic queries with the API.

The tutorial assumes you can perform basic cURL requests with a command-line tool or app such as Postman.

Before You Start

You will need:

• A Facebook Developer Account.
• An Instagram account with media.
• A public website that you own. This can be a generic free one like a Github Page or Heroku web app, or your actual website.
• A command-line tool such as Terminal or an app like Postman that can perform cURL requests.

Step 1: Create a Facebook App

Go to developers.facebook.com, click My Apps, and create a new app and choose the Consumer or None app type.

Once you have created the app and are in the App Dashboard, navigate to Settings > Basic, scroll to the bottom of page, and click Add Platform.

Choose Website, add your website’s URL, and save your changes. You can change the platform later if you wish, but for this tutorial, use Website.

Step 2: Configure Instagram Basic Display

Click Products, locate the Instagram Basic Display product, and click Set Up to add it to your app.

Scroll to the bottom of the page and click Create New App.

In the form that appears, complete each section using the guidelines below.

Display Name

Enter the name of the Facebook app you just created.

Valid OAuth Redirect URIs

Enter your website’s URL. Normally this would be a dedicated URI that can capture redirect query string parameters, but for this tutorial your website’s URL will be fine.

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

After you enter a URL, save your changes and check the URL again; we may have appended a trailing forward slash depending your URL structure. Copy the complete URL somewhere since you will need it in later steps to get authorization codes and access tokens.

Deauthorize Callback URL

Enter your website’s URL again. Eventually you will have change this to a URL that can handle deauthorization notifications, but for the purposes of this tutorial, you can re-use your website URL.

Data Deletion Request Callback URL

Enter your website’s URL once again. Just like the Deauthorize Callback URL, you will eventually have change this to a URL that can handle data deletion requests, but for now you can re-use your website URL.

App Review

Skip this section for now since you will not be switching the app to Live Mode during the tutorial.

Step 3: Add an Instagram Test User

Navigate to Roles > Roles and scroll down to the Instagram Testers section. Click Add Instagram Testers and enter your Instagram account’s username and send the invitation.

Open a new web browser and go to www.instagram.com and sign into your Instagram account that you just invited. Navigate to (Profile Icon) > Edit Profile > Apps and Websites > Tester Invites and accept the invitation.

Your Instagram account is now eligible to be accessed by your Facebook app while it is in Development Mode.

Step 4: Authenticate the Test User

Construct the Authorization Window URL below, replacing {app-id} with your Instagram app’s ID (from the App Dashboard > Products > Instagram > Basic Display > Instagram App ID field) and {redirect-uri} with your website URL that you provided in Step 2 ("Valid OAuth Redirect URIs"). The URL must be exactly the same.

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

For example:

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

Open a new browser window and load the Authorization Window URL. It should appear and display your Instagram user’s name, the app’s name, and a description of the permissions your app is requesting.

Authenticate your Instagram test user by signing into the Authorization Window, then click Authorize to grant your app access to your profile data. Upon success, the page will redirect you to the redirect URI you included in the previous step and append an Authorization Code. For example:

https://socialsizzle.herokuapp.com/auth/?code=AQDp3TtBQQ...#_

Note that #_ has been appended to the end of the redirect URI, but it is not part of the code itself. Copy the code (without the #_ portion) so you can use it in the next step.

Step 5: Exchange the Code for a Token

Open your command line tool or app that supports cURL requests and send the following POST request to the API.

curl -X POST \
  https://api.instagram.com/oauth/access_token \
  -F client_id={app-id} \
  -F client_secret={app-secret} \
  -F grant_type=authorization_code \
  -F redirect_uri={redirect-uri} \
  -F code={code}

Replace {app-id}, {app-secret}, {redirect-uri}, and {code} with your Instagram app ID, Instagram app secret, your redirect URI, and the code we sent you. Make sure that your redirect URI exactly matches the one you specified in the previous step, including trailing forward slashes if the App Dashboard added them when you configured your Instagram app.

For example:

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

Upon success, the API will return a JSON encoded object containing a short-lived Instagram User Access Token, valid for 1 hour, and your Instagram test user’s ID:

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

Copy the access token and user ID so you can use them in the next step.

Step 6: Query the User Node

Use your command-line tool or app and the cURL request below to query the User node for your user’s ID and username. Replace {user-id} and {access-token} with the ID and access token you received in the last step.

curl -X GET \
  'https://graph.instagram.com/{user-id}?fields=id,username&access_token={access-token}'

For example:

curl -X GET \
  'https://graph.instagram.com/17841405793187218?fields=id,username&access_token=IGQVJ...'

Alternately you can query the Me node, which will examine your token, determine the ID of the Instagram user who granted the token and query that User. For example:

curl -X GET \
  'https://graph.instagram.com/me?fields=id,username&access_token=IGQVJ...'

Upon success, the API will respond with your Instagram user’s ID and username:

{
  "id": "17841405793187218",
  "username": "jayposiris"
}

Next Steps

Now that you know how to get a token and perform a basic query, read our guides to learn more about what you can do with the API.