Authenticate your API Requests

We recommend that you use the sandbox environment for accessing the Tenant portal, if you are trying to authenticate your API request for the first time.

Duck Creek Payments Orchestrator uses a secure and robust authentication process to validate API calls. To prevent unauthorized parties from using your account, Payments Orchestrator uses a multi-step authentication method.

Before you Start

Before you start following this guide, you need to have generated your Tenant API Key.

How it works?

Before making any calls to the Payments Orchestrator APIs, you must generate an HMAC Token. The HMAC token is used by Payments Orchestrator to securely and uniquely identify you.

However, generating and verifying an HMAC token for every single API request is computationally expensive.

To speed up the process, Payments Orchestrator asks you to submit your HMAC token through the secure HMAC endpoint and offers you an Access Token in return. Using this Access Token, you can make subsequent calls to any other Payments Orchestrator APIs.

Follow this guide to learn how you can generate an Access Token using your HMAC token.

How to Authenticate API Requests?

Step 1: Create a HMAC Token

Use your API Key (Private and Public Keys) to create a HMAC token from your request.

You can implement the program to generate HMAC token by yourself. Alternatively, you can use the handy form (below) to generate HMAC token.

Public Key

Private Key

Step 2: Generate an Access Token and Copy it

Make a call to our HMAC endpoint using the HMAC token as a part of Authorization header to generate an Access Token.

API Header SyntaxAPI Header ExampleAPI Response Example

Copy

Copied

Authorization: Hmac {hmactoken}

Copy

Copied

Authorization: Hmac {are299c5u99lf2XQy3GBP57fOzxGmEU90ooveijYIRySP8xKqjM=}

Copy

Copied

{
  "accessToken": "eyJhbGciOiJIUzI1N...9UAUBNuyPN6Xg",
  "expires": 1614350382
}

An Access Token will expire after 120 minutes. Check the expires property of the API response determine how long the Token will remain valid.

If an Access Token has expired, call the HMAC endpoint again to regenerate new Access Token.

Step 3: Build the Request Header

Use the Access Token in the Authorization header of the subsequent API Calls. Most APIs also require x-account-id and x-tenant-id headers as a part of request, where the former indicates your Account ID and the latter indicates your Tenant ID.

API Header SyntaxAPI Header Example

Copy

Copied

Authorization: Bearer {accesstoken}
x-account-id: <your-account-id>
x-tenant-id: <your-tenant-id>
Content-Type: application/json

Copy

Copied

Authorization: Bearer {eyJhbGciOiJIUzI1N...9UAUBNuyPN6Xg}
x-account-id: 49bder42-90d9-46b1-b120-f6b347d621a0
x-tenant-id: 60452f48-5d48-4bc0-ab6f-5cr3ee411f63
Content-Type: application/json

You can copy your Tenant ID and Account ID from the Tenant Info page. To access the Tenant Info page, click on the Info submenu under the Tenant menu from the left-sidebar of your Tenant Portal.

Troubleshooting

My access to an endpoint has been denied.

While the error message that you receive as a part of the API Response will give you more details on why your access was denied, it will usually happen for one of the following reasons.

You don't have the correct permissions to access the Payments Orchestrator APIs.
The HMAC token used to generate an Access Token is invalid.
Your Access Token has expired.

To resolve the issue, repeat the authentication steps described above. If that doesn't work, contact your Tenant Administrator.

When will my Access Token expire?

See the expires property of the HMAC endpoint response to assess the length of time your Access Token will remain active.

The value shown next to the expires property is a Unix (Epoch) timestamp. Use this form to convert the Unix timestamp to a human-readable date.

Epoch