Skip to main content

Authentication

The External API uses JWT bearer tokens. You exchange a clientId and secret for a JWT, then send the JWT on every subsequent request.

Get a JWT​

Run the mutation below — fill in your clientId and secret in the variables, click Run, then Save as JWT to store the token for use by other interactive examples in these docs.

mutation authenticate($input: AuthenticateInput!) {
authenticate(input: $input) {
  authenticationPayload {
    jwt
  }
}
}

Use the JWT​

Send the token as a Bearer credential on every request:

POST /graphql
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{ "query": "{ ... }" }

The runnable examples elsewhere in these docs read the saved JWT from your browser's localStorage automatically.

What's on the token​

Once you authenticate, the JWT carries:

  • sub / clientId — the API key's client ID.
  • organizationId — the board (organization) this key is provisioned for. Every query is filtered to this ID automatically — you never pass it as an argument.
  • scope — one or more <feature>:read or <feature>:write claims, controlling which queries and mutations you can call. The features are organization, members, and events.

Errors​

  • Invalid credentials — the clientId doesn't exist, or the secret doesn't match.
  • API key has been revoked — the key has been deactivated. Contact Unioo to issue a new one.

Tokens are time-limited; obtain a new one when it expires by calling authenticate again.