Core GraphQL API Authorization

The Administrate Core GraphQL API uses the OAuth 2.0 protocol for authentication and authorization. Administrate supports the OAuth 2.0 Authorization Code flow for web and installed applications.

To begin, obtain OAuth 2.0 client credentials by creating an application.

Authorization Code Flow

1. Obtain OAuth 2.0 credentials.

Create a Client Application to obtain OAuth 2.0 credentials (Client Key and Secret). You will be asked to specify an OAuth Callback URL that will be used during the Authorization Code Flow.

2. Start Flow.

The authorization flow begins when your application redirects a browser to the Administrate authorization url.

Normally this only needs to be done once for a user, to allow them to explicitly authorize you to access the data in their Administrate Instance. Once you have followed this flow you will have a Refresh Token you can store to get Access Tokens for subsequent sessions. The authorization flow will need to start again if the user revokes access, invalidating the Access Tokens and Refresh Tokens.

https://auth.getadministrate.com/oauth/authorize?response_type=code&client_id=<Client Key>&instance=<Instance>

General

Request parameters

redirect_uri (optional) If not specified it will use the OAuth Callback URL specified when you created the Client Application.

instance (optional) The instance that you want the user to authenticate against. This should be the full URL of an Administrate instance. If not specified the user will be asked for their instance.

Administrate handles the user authentication. After the authentication the user will be redirected back to the OAuth Callback URL specified when you created your client application with an Authorization Code as a query parameter.

https://my.application.com/callback_url?code=UiMwWksE7R4MXk3VZf3D6p8cXSOxM1

3. Obtain an access token from the Administrate Authorization Server.

Before your application can access private data using a Administrate API, it must obtain an access token that grants access to the users Administrate Instance.

The Authorization Code can be exchanged for a token by posting a web request to:

https://auth.getadministrate.com/oauth/token?code=<Authorization Code>&grant_type=authorization_code&client_id=<Client Key>&client_secret=<Client Secret>&redirect_uri=<OAuth Callback URL>

General

Request parameters

redirect_uri (optional) If the OAuth Callback URL was included in the initial authorization request, it will be required here as well.

Response

If the parameters above are valid you will receive a JSON response with an Access Token and Refresh Token, e.g.:

{
  "expires_in": 3600,
  "refresh_token": "Nh2LJd5STKsdp9OU8eRytC5110lgWU",
  "token_type": "Bearer",
  "access_token": "3rHmesphmjWlQdhr4tWjGHXw166ySI",
  "scope": "instance"
}

The access_token is used as an Authentication Token for the Administrate API. It will be valid for 1 hour.

The refresh_token can be stored and used to gain further Access Tokens once this one expires. The Refresh Token will become invalid if:

• A user removes your access
• It hasn't been used in six months

4. Send the Access Token to the Administrate API.

After an application obtains an Access Token, it sends the token to the Administrate API in an HTTP authorization header when making GraphQL queries. This will run the queries as the User that authenticated at the start of the flow, against the data in their Administrate Instance.

curl -v https://api.getadministrate.com/graphql \
    -H 'Authorization: bearer <TOKEN>' \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{"query": "{hello}"}'

5. Refresh the Access Token

If the Access Token reaches its expiry. The Refresh Token can be used to get a new one.

The Refresh Token can be exchanged for a token by posting a web request to:

https://auth.getadministrate.com/oauth/token?refresh_token=<Refresh Token>&grant_type=refresh_token&client_id=<Client Key>&client_secret=<Client Secret>&redirect_uri=<OAuth Callback URL>

General

Request parameters

redirect_uri (optional) If the OAuth Callback URL was included in the initial authorization request, it will be required here as well.

Response

You will receive a JSON response with a new Access Token, e.g.:

{
  "expires_in": 3600,
  "refresh_token": "rR94O224oqwWLXu0Zns9lh3VE2v16R",
  "token_type": "Bearer",
  "access_token": "3rHmesphmjWlQdhr4tWjGHXw166ySI",
  "scope": "instance"
}