Sandbox Mode

Every new app created on the Instagram Platform starts in Sandbox mode. This is a fully functional environment that allows you to test the API before submitting your app for review. Sandbox mode is ideal for developers who are new to the Instagram Platform and want to explore the API Platform, as well as for teams that need multiple clients for development, staging, and other non-live environments.
To help you develop and test your app, the users and media available in Sandbox mode are real Instagram data (i.e. what is normally visible in the Instagram app), but with the following conditions:
  • Apps in sandbox are restricted to 10 users
  • Data is restricted to the 10 users and the 20 most recent media from each of those users
  • Reduced API rate limits
The next section will explain these conditions in more detail and how you can leverage Sandbox mode to build and test your app. Only apps that are reviewed and approved will be able to get out of Sandbox mode and be available to any Instagram user.

Sandbox Users

When you want to start working with the Instagram API Platform, you can register a new app that will start in Sandbox mode. Since this mode is meant for development, apps in Sandbox mode are not visible to the general public, but instead are only visible to a limited set of up to 10 authorized 'sandbox users'. Only these users will be able to test and authenticate your app.
To manage the list of sandbox users for a given app, you can go to the Sandbox tab in your client configuration screen. There you will be able to add and remove the sandbox users for your app, up to a maximum of 10 users. Note that the admin of the app is always a sandbox user, so you can effectively add up to 9 additional 'sandbox users'.
After adding users to the list, they will have to accept your invitation before actually becoming sandbox users. To accept the invitation, they can go to the 'Sandbox Invites' button on the top bar of the developer site. In the 'Sandbox Invites' page people can accept or reject invitations, and also stop being sandbox users for a given app.
Note: a user can become a sandbox user of up to 5 apps. You will not be able to invite someone that is already a test user of 5 apps.

Login Permissions

Now that you have some sandbox users, you can have them go through the authorization flow and generate an access token. The OAuth dialog will display a warning that the app being authorized is in sandbox mode, which is a good reminder that the OAuth dialog will work only for sandbox users. If anyone else tries to authorize your sandbox app, they will see a OAuthForbiddenException error message.
Apps in sandbox can use any of the login permissions available. This will allow you to generate access tokens that have any of the scopes required to test the behavior of the API endpoints. While this is great for testing, remember that you still have to go through the permission review process if you want to be granted the ability to use the permissions when you go live.

API Behavior

The behavior of the API when you are in sandbox mode is the same as when your app is live, but comes with the following restrictions:
  • Data is restricted to sandbox users and the 20 most recent media from each sandbox user
  • Reduced API rate limits
The first point is important and it means that the API behaves as if the only users on Instagram were your sandbox users, and the only media ever posted were the last 20 for each of these users.
For example, if you query the /users/{user-id}/ endpoint and the {user-id} is a sandbox user, then you will get the normal API response; but if the {user-id} is not a sandbox user, you will get a APINotFound error.
As another example, let's consider an endpoint that returns a list of media: /tags/{tag-name}/media/recent. The response returned by this endpoint will contain only media with the given tag, as expected. But instead of returning media from any public Instagram user, it will return only media that belongs to your sandbox users, restricted to the last 20 for each user.

Going Live

To get out of Sandbox mode, you need to submit your app for review. If your app falls into the approved use cases and gets approved, it will automatically go live. At this point any Instagram user will be able to authorize your app, but you will have access only to the permissions that you were granted during the review. If you need access to more permissions, you can submit for review again and you will not lose access to the permissions that you have already been granted.