How to authenticate

Sending the access token

Send the access token on every HTTP request to the API:

Authorization: Bearer <your access token>

Which organization's data you can see follows your signed-in account and permissions.

Using the login mutation

You can sign in with email and password by calling the login mutation. It returns TokenInfo:

Example; sign in and read the access token:

mutation Login($email: String!, $password: String!) {
  login(email: $email, password: $password) {
    token
    refreshToken
    expiresIn
  }
}

Supply the credentials as GraphQL variables, injected at runtime from a secret manager:

{ "email": "[email protected]", "password": "<from your secret store>" }

Use the returned token as <your access token> in the Authorization header for subsequent queries and mutations (for example request, requests, createCompensations).

Always call the API over HTTPS so credentials and tokens are protected in transit.

Refreshing the access token

When the access token expires, call the refreshToken mutation. Pass refreshToken with the value you received from login (or from a previous refreshToken response). If your integration uses cookies and the server supports it, you may omit the argument where the refresh token is read from the session.

mutation RefreshToken($refreshToken: String!) {
  refreshToken(refreshToken: $refreshToken) {
    token
    refreshToken
    expiresIn
  }
}

Variables (inject the stored value at runtime; never paste tokens into the operation body):

{ "refreshToken": "<from your secret store>" }

Use the new token in the Authorization header going forward.