Authentication

How to retrieve and use a bearer token.

API Username/Password

To connect to GraphQL, you will need an API username and password.

These are currently issued by our support staff, so please contact [e-mail] and let us know your Toggle account name. You'll need to contact us from a verified email address on your Toggle account.

Tokens

GraphQL uses JWT tokens to authenticate API requests. So before making any request to a protected resource, you'll need to make sure you have generated a valid token, as you'll need to include this in your authorization header on each request.

Generating a token

To generate your token, use your API username/password to make a request to the loginUser query, which will return an Authorization header containing your token:

query($email:String,$username:String, $password:String!){ 
loginUser(email:$email,username:$username,password:$password) 
{
    id
  }
}

Try it now on our API explorer

Note that you can login with either an email or a username via loginUser.

Your X-Authorization token is returned on the loginUser response. Note - there is currently Authorization and X-Authorization tokens returned (they are the same). We are depreciating the Authorization header, so use the X-Authorization header to futureproof the integration.

Token

Using tokens in requests

Whenever the user wants to access a protected route or resource, the user agent should send their token in the Authorization header using the Bearer schema. The content of the header should look like the following:

Authorization: Bearer 

Refreshing tokens

As a token is time limited, it will require a refresh after 60 minutes.

When you make a new request and the Authorization header is returned, you should start using the new token for the next request.

You will need to programmatically update your token and store it securely in your system each time you retrieve a new token, using it until such time that it is refreshed.

Authentication failure

If you are not authorised and you attempt to make a request to a protected query or mutation, the API will return JSON with errors.

{
  "errors": [
    {
      "message": "Unauthorized",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "customer_facing": false
    }
  ]
}

Further reading

It is worthwhile reading the introduction from JWT which summarises how JSON Web Tokens work for more information.