Generate an authorization token to use when making API requests

In order to make use of the V4 APIs, we will first need to authenticate your client with our API service. Each request made to any V4 resource requires a unique authorization bearer token to be provided in your request headers. These tokens are automatically generated by JOOR.

A new token can be requested at any time by making a POST request to the /auth resource and providing your unique identification credentials. You can have multiple tokens active simultaneously.

You must provide the following credentials as multipart/form data when requesting a new token:

  • client_id (provided by JOOR)
  • grant_type (set to a default string value of "password")
  • client_secret (provided by JOOR)
  • username (provided by JOOR)
  • password (provided by JOOR)

Note that the JOOR Sandbox and Production environments each have their own endpoints:


See example below of requesting a new bearer token, which could then be used to make API requests to other services in the V4 API suite.

curl --location --request POST '' \
--header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
--form 'client_id=' \
--form 'grant_type=password' \
--form 'client_secret=' \
--form 'username=' \
--form 'password='
from requests import Request, Session

def authenticate(subdomain='atlas-sandbox'):
  auth_url = "https://{}".format(subdomain)

  data = {
      'client_id': 'ua3feFAE8a3kln8883Fjka93jkafliej3fnFN3k3a', # provided by JOOR
      'grant_type': 'password', # always "password"
      'client_secret': '478UY5q9Kc3sfwPc8yWmFipqvKtcUueWVWAOdAMeQtTICsPfghwWIIxmKVzxamNEtJ0DzCbo6DlVoniav52LOzltpNPVkOXr2i0ToNFTqlpitUMdaFBvqECsa26ug2uq', # provided by JOOR
      'username': '[email protected]', # provided by joor
      'password': 'S3CUR3pa$$w0rd' # provided by JOOR

  request = Request(
          'client_id': (None, data['client_id']),
          'grant_type': (None, data['grant_type']),
          'client_secret': (None, data['client_secret']),
          'username': (None, data['username']),
          'password': (None, data['password']),
          'g-recaptcha-response': (None, 'xxx'),

  s = Session()
  response = s.send(request)
  return response

if __name__ == '__main__':
  auth_response = authenticate(subdomain='atlas-sandbox') # or 'atlas' for the production environment

This is an example payload in JSON format, with a response status code of 200:

    "access_token": "aaaaaaaaaa.bbbbbbbbbb.cccccccccc-dddddddddd",
    "expires_in": 36000,
    "refresh_expires_in": 86400,
    "refresh_token": "eeeeeeeeee.ffffffffff.gggggggggg",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "hhhhhhhhhh-jjjj-kkkk-llll-mmmmmmmmmmmm",
    "scope": "email profile"


Authorization token expiration

Authorization tokens are temporary and reset in n seconds, where n is specified by the expires_in property of the payload returned by the /auth resource.

Now you can make an API request to any V4 endpoint by including the access_token in the Authorization header.