Toggle Developers
HomeAcademy
  • Welcome
  • GraphQL
    • Getting started
    • Exploring our API
    • Authentication
    • API playground
    • Error handling
  • Key concepts
    • Overview
      • Orders, Transactions & Line Items
      • Card number formats
  • Basics
    • Create a card
    • Check a card balance
    • Redeem a card
  • Webhooks
    • Overview
      • Getting started
      • Authentication & responses
    • Events
      • Card.balance_adjusted
      • Card.card_reference_updated
      • Card.expiry_reminder
      • Card.registered
      • Card.send_recipient_email
      • Card.resend_recipient_email
      • Order.created
      • Order.cancelled
      • Order.send_receipt_email
      • Order.send_cancellation_email
      • Payment.failed
      • Payment.review_opened
      • Fulfilment.dispatched
  • Partner Guides
    • EPOS & Ordering
      • Overview
      • Accreditation
      • Configuration variables
      • Playground examples
      • Physical card orders
      • Custom validity rules
      • Balance check
      • Redemptions & top-ups
      • Reversals
    • Guest gratuity
      • Overview
      • Accreditation
      • Configuration variables
      • Playground examples
      • Creating a card
      • Cancelling a card
      • Register a card
    • CRM
      • Overview
      • Historic data via GraphQL
      • Real time data via webhooks
Powered by GitBook
On this page
  • API Username/Password
  • Tokens
  • Generating a token
  • Using tokens in requests
  • Refreshing tokens
  • Authentication failure
  • Further reading
  1. GraphQL

Authentication

How to retrieve and use a bearer token.

PreviousExploring our APINextAPI playground

Last updated 5 months ago

API Username/Password

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

You can connect existing integrations or generate new API user credentials under Settings > . Choose the "Other" category for custom applications.

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

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.

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 which summarises how JSON Web Tokens work for more information.

Integrations
Try it now on our API explorer
introduction from JWT
Token