Skip to main content

Authentication

Access token​

Every request to the OMS API requires an access token: a request without a valid token is rejected with HTTP status 403 before even reaching the GraphQL layer (see Errors). In addition, each query and mutation requires specific permissions granted to your token. Contact Calicantus at developers@calicant.us to obtain an access token before using the API.

Authorization header​

Send the token in a Bearer Authorization header on every request:

Authorization: Bearer <token>

where <token> is your access token (a single space between Bearer and the token).

In the Playground built into these docs you only need to paste the token in the Access token field of the toolbar: the header is added to every request for you. In a desktop GraphQL client, add it in the client's headers settings.

Calling the API directly​

If you integrate via code instead of a GUI client, send a POST request to the GraphQL endpoint with a JSON body containing the query (and optional variables), the Authorization header, and Content-Type: application/json. The example below uses the staging endpoint (see Endpoints for the staging and production URLs) and the me query, which returns the name and the permissions of your token:

curl -X POST https://api.oms-staging.calicant.us/api/graphql/v1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  --data '{"query":"{ me { name permissions } }"}'
note

The name and the permission list in the response below are examples: you will see your own.

{
  "data": {
    "me": {
      "name": "Your name",
      "permissions": ["api_user:query:me", "api_user:read"]
    }
  },
  "extensions": {
    "queryComplexity": 3,
    "bucketBalance": 9997,
    "bucketRestoreRate": 100
  }
}