How do I efficiently manage API authorization and access tokens?

Last Updated November 12th, 2018

As outlined in our platform documentation, access to PokitDok’s APIs is managed via the OAuth2 secure authorization framework. At the heart of our OAuth2 workflow is the access token which serves as your authorization key for requests to our platform.

Access tokens are generated and issued to authenticated API clients. The access token is used by PokitDok’s APIs to ensure that API clients have authenticated and are permitted to access requested resources. Access tokens are sent with each API request and are intended to be reused until they expire. PokitDok’s access tokens expire after 1 hour.

It is important to use access tokens efficiently. Inefficient use, such as rotating access tokens prior to expiration or generating access tokens for each request, may subject your requests to unnecessary rate limiting or other issues, causing your requests to fail.

For these reasons we strongly recommend using one of our client libraries, since they provide the ability to instantiate a PokitDok client connection object that supports automatic handling of token retrieval, expiration, and rotation. The client libraries encapsulate token management, allowing you to focus on your application design and integration with PokitDok’s APIs.

The key to efficient token use is to ensure that the PokitDok client is instantiated only once, and then referenced for each subsequent request. While specific implementation details may differ per programming language and application, the following Python script provides a basic implementation that provides a reusable PokitDok client.


import os

import pokitdok


# The PokitDok client should be instantiated here in the parent namespace,

# thereby allowing it to be held in memory throughout the run of the program.


pd_client = pokitdok.api.connect(



  auto_refresh=True # usually True by default in our other client libraries



def make_eligibility_call(pd_client, params):


  A trivial example of a function that can be used to make a call to our

  Eligibility API.

  Note that it would be a mistake to instantiate the client here, since a

  fresh instance would be created (requiring a new “access_token“) upon

  each call to this function.

  :param pd_client: The long-lived PokitDok client instance.

  :param params: The parameters for the Eligibility request.

  :return: The client response object.


  # Use the pd_client object to call the Eligibility API with the passed params

  client_response = pd_client.eligibility(params)

  return client_response


# Define the Eligibility request params

params = {

  “member”: {

      “birth_date”: “1970-01-01”,

      “first_name”: “Jane”,

      “last_name”: “Doe”,

      “id”: “12345678910”


  “trading_partner_id”: “MOCKPAYER”



# Call the Eligibility API

response_data = make_eligibility_call(pd_client, params)

# …do something with response_data…

Didn't find what you were looking for?

Contact Us