Core GraphQL API Authorization

The Administrate Core GraphQL API uses the OAuth 2.0 protocol for authentication and authorization.

Administrate supports two OAuth 2.0 flows:

• Authorization Code flow for user-delegated access (web and native applications)
• Client Credentials flow for server-to-server authentication (machine-to-machine)

Security Best Practices: - Always use HTTPS for all OAuth endpoints and redirects - Use state parameter to prevent CSRF attacks - Store tokens securely and never expose them in client-side code

Authorization Code Flow

The Authorization Code flow is used when your application needs to act on behalf of a user, requiring their explicit consent and authentication. Use for: Applications that need to act on behalf of a user

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 URI that will be used during the Authorization Code Flow.

2. Start Authorization 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 Tenant. 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>&state=<Random State>

Request parameters

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. Validate Callback and Exchange Authorization Code

Always validate the state parameter matches your stored value to prevent CSRF attacks. Before your application can access private data using a Administrate API, it must obtain an Access Token that grants access to the users Administrate tenant.

Exchange the Authorization Code for an Access Token by making a POST request to:

https://auth.getadministrate.com/oauth/token

Request Headers

Content-Type: application/x-www-form-urlencoded

Request Body Parameters

Example Request

curl -X POST https://auth.getadministrate.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "code=UiMwWksE7R4MXk3VZf3D6p8cXSOxM1" \
  -d "redirect_uri=https://your.application.com/callback"

Response

Success response (200 OK):

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

4. Use Access Token for API Requests

Include the access token in the 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 tenant.

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

5. Refresh Access Token

When the access token expires (after 1 hour), use the refresh token to obtain a new access token:

https://auth.getadministrate.com/oauth/token

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

Request Body Parameters

Example Request

curl -X POST https://auth.getadministrate.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "refresh_token=Nh2LJd5STKsdp9OU8eRytC5110lgWU"

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"
}

Client Credentials Flow

The Client Credentials flow is used for server-to-server authentication where your application needs to access the Administrate API with its own service user, rather than getting explicit consent from a user.

1. Obtain Client Credentials

As a tenant Admin, go to the Control Panel - Authorized Applications. Create a new set of Client Credentials and choose the Service User you would like this client to authorize on behalf of. This will give you a Client ID and Client Secret that can be used for authentication.

Important: Never expose client credentials in client-side code, and ensure they are stored and shared safely.

2. Request Access Token

Make a POST request directly to the token endpoint:

https://auth.getadministrate.com/oauth/token

Request Headers

Content-Type: application/x-www-form-urlencoded

Request Body Parameters

Example Request

curl -X POST https://auth.getadministrate.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

Response

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

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

Note: Client Credentials flow typically does not return refresh tokens as the client can request new tokens directly.

3. Use Access Token for API Requests

Include the access token in the Authorization header when making GraphQL queries. In the Client Credentials flow, queries will run as the configured service user (the application), with access determined by the permissions assigned to that service user in the Administrate tenant.

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

4. Revoking Client Credentials

Client Credentials can be revoked by tenant admins on the same screen they were created from (Control Panel -> Authorized Applications). Revoking a set of Client Credentials, will mean the Client ID and Secret can no longer be exchanged for new Bearer Tokens, and should be done immediately if Credentials are exposed.