Authenticate your API Requests

Duck Creek Payments uses a secure and robust authentication process to validate API calls. To prevent unauthorized parties from using your account, Payments 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 APIs, you must generate an HMAC Token. The HMAC token is used by Payments 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 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 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.

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
Authorization: Hmac {hmactoken}
Authorization: Hmac {are299c5u99lf2XQy3GBP57fOzxGmEU90ooveijYIRySP8xKqjM=}
  "accessToken": "eyJhbGciOiJIUzI1N...9UAUBNuyPN6Xg",
  "expires": 1614350382

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
Authorization: Bearer {accesstoken}
x-account-id: <your-account-id>
x-tenant-id: <your-tenant-id>
Content-Type: application/json
Authorization: Bearer {eyJhbGciOiJIUzI1N...9UAUBNuyPN6Xg}
x-account-id: 49bder42-90d9-46b1-b120-f6b347d621a0
x-tenant-id: 60452f48-5d48-4bc0-ab6f-5cr3ee411f63
Content-Type: application/json


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.

  1. You don't have the correct permissions to access the Payments APIs.
  2. The HMAC token used to generate an Access Token is invalid.
  3. 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.

Copyright 2024 Duck Creek Technologies. All Rights Reserved.