Authentication Overview

Important

From July 1st 2021, Refresh Tokens are deprecated and not issued anymore as part of the default behavior for authentication. According to the RFC for Client Credentials grant flow, A refresh token SHOULD NOT be included in the response of the auth request. We urge all developers to adjust their clients for this behavior. Currently, we allow for this possibility by passing access_token_only scope while making the Auth request. More details can be found here.

From July 1st 2021, the scope access_token_only will not be required anymore to issue only access tokens as this will become the default behavior for every authentication request.

The zDirect API uses OAuth 2.0 to authenticate and authorize client access.

This section describes how to use the Authentication API to request access tokens, and how to use these to construct authentication headers for your calls to the zDirect API.

The sample httpie calls provided in this guide use the -a argument to construct headers. In your application code, use the appropriate authentication library to construct an HTTP authentication header. Such libraries are found in most relevant languages.

For more information on httpie, see Testing with httpie.

For handling authentication. The following steps generate an access token:

  1. Create an app in the zDirect Portal. In this context, an app is essentially an OAuth client.
  2. Grant the app any necessary scopes.
  3. Pass the app’s client ID, client secret and scope access_token_only to an access token request and call the Authentication API. The access token is returned.
  4. For subsequent calls to the zDirect API, build an Authorization HTTP header and use your access token as the bearer token.
  5. When your access token expires or is invalidated, request a new access token.

For detailed instructions for each step, see below.

Best Practices

  • Be sure to secure your credentials - especially your client ID and client secret. For more information, see the "Securing your Credentials" section in Requesting an Access Token.
  • Use each access token for as long as possible (up to its expiration).
  • Use the access_token_only scope if you don't need refresh tokens.
  • Use the expires_in value in the response body of the access token request to schedule additional token requests.

Additional Resources

Contact Support