Using OAuth 2.0 and Postman to access our GraphQL API

Table of Contents

1. Generating a Client ID and Client secret
2. Using Postman to get an access token
3. Troubleshooting
   1. Error: Invalid Request Invalid client_id parameter value
   2. Error: invalid_client

You'll find how to access our GraphQL API and authenticate using OAuth 2.0 on our Developer Portal. On that page, you'll learn how to authenticate an application that you built or use with an Administrate instance.

However, if it's your first time using OAuth 2.0 or if you'd like to get set up quickly, you may want to use Postman. This article will show you how to get an access token in Postman.

Generating a Client ID and Client secret

First, we'll create an app in a developer account. Create a developer account if you haven't already, so you can start creating developer apps. Note that there is no limit to the number of apps that you create in your developer account. Also, apps are not limited to your developer instance, and they can be installed in any Administrate instance by a superuser.

1. Go to https://developer.getadministrate.com/account/my-apps

2. Click “Create application”

3. Enter any application name you like. The name will just show when you connect the app with an Administrate instance.

4. For the “OAuth callback URL” field: If you've already created a GraphQL app supporting OAuth 2.0, enter your OAuth callback URL here, otherwise, you can use Postman for development. Postman is a service for building and using APIs. They provide an OAuth callback URL that can be used for OAuth 2.0. Their OAuth callback URL is https://postman-echo.com/get

5. Enter a description if you like.

6. Click “Create application” now. This will generate an API Key (also called Client ID) and API Secret (also called Client Secret). Copy both.
   
   

Using Postman to get an access token

1. Download and install Postman if you haven't already, and launch Postman on your computer.

2. Download the file available at the bottom of this page. This is a template request to authenticate with OAuth 2.0, so you don't have to fill in all the fields manually.
   Its name is “OAuth 2 with Administrate.postman_collection.json”.

3. To import this file into Postman, open Postman and click “Import” and drag and drop the file onto the window, or select it in your file manager. For more info on this step, you can refer to this page. The file is named “OAuth 2 with Administrate.postman_collection.json”.

4. After the file has been imported, go to the “Administrate” folder and select “OAuth 2 with Administrate for GraphQL” in the left-hand sidebar.
   
   

5. Once you've selected it, click the “Authorization” tab in the main window.
   
   

6. In the right-hand side column, you'll see information about tokens. You don't have an access token yet, but it'll show there soon. Scroll down in that column until you see “Client ID” and “Client Secret”.

7. Paste the “Client ID” and “Client Secret” that you got at the end of the previous section.

8. Don't change any other values. These should be already been filled in when you imported the file. In case you're missing any of them, please find them below.
   

   Callback URL: https://postman-echo.com/get – or the one you set in your app.
   Auth URL: https://auth.getadministrate.com/oauth/authorize
   Access Token URL: https://auth.getadministrate.com/oauth/token
   Scope: instance
   Client Authentication: “Send client credentials in body”

9. Scroll down to the bottom until you see “Get New Access Token” and click “Get New Access Token”.
   
   

10. This will open a pop-up window. Enter the address of your Administrate instance first, e.g., http://abc.administrateapp.com, and click “Next”.
    
    

11. Then log in as an existing user on that instance. Click “Sign in”.

12. If you logged in successfully, you'll see a prompt to allow the app to access the instance. Click “Allow access”.
    
    

13. Postman will show the access and refresh tokens now!
    You can rename your token details in Postman to remember what they are for. If you'd like your developers to use them, copy the access token and refresh token, and send them the “Client ID” and “Client Secret” as well. They'll need these to use the refresh token and get a new access token after it expired.
    
    

Now you can use the access token to authenticate your API calls. You can also use the refresh token, “Client ID” and “Client Secret” to get a new access token when it expired. Note that your refresh token does not expire and it will remain the same. For more details, please refer to our Developer Portal.

Troubleshooting

Error: Invalid Request Invalid client_id parameter value

If you get an error saying that there was an error processing your request, with “Invalid Request Invalid client_id parameter value”, it is likely that your client ID is incorrect. In this case, go to your developer account and copy the value for “API Key” again, then replace the client_id value in Postman.

Error: invalid_client

If you get an error saying that the authentication failed with the error “invalid_client”, it is likely that your client secret is incorrect. This may happen if you regenerate the API Secret in your developer account. In this case, go to your developer account and copy the secret again, then replace the client_secret in Postman.