The Hello Clever API uses a two-step authentication model. You first obtain an access token by presenting your app-id and secret-key, then include that token as a Bearer credential on every subsequent request. This page walks you through getting your credentials, requesting a token, and using it securely.

​
Before you start

You need an active Merchant Account and a linked site before you can generate credentials. Follow the Obtaining Integration Keys guide to complete that setup.

​
Step 1: Obtain your credentials

1

Log in to the Merchant Portal

Open the portal for your target environment:
2

Create or open a linked site

Click + Link Site in the top-right corner and complete the wizard. Choose Custom APIs as the integration type for direct API access.
3

Copy your App ID and Secret Key

In the App ID & Key section of the site details, you will find:
  • App ID (app-id): a unique identifier for your linked site
  • Primary Secret Key (secret-key): a confidential key used to authenticate requests
Store both values in a secrets manager or environment variable. Never commit them to source control.

​
Step 2: Request an access token

Exchange your app-id and secret-key for a short-lived Bearer token by calling the access token endpoint.
Use the sandbox endpoint (https://api.cleverhub.co) and sandbox credentials when developing or testing. Switch to the production endpoint only when you are ready to go live.

​
Step 3: Authorise API requests

Include the access token in the Authorization header of every API request:

​
Direct header authentication

Some endpoints — particularly the S2S Card API — accept app-id and secret-key directly as request headers instead of a Bearer token:
Check the reference documentation for the specific endpoint you are calling to confirm which authentication method it requires. The /v1/payment_gateways/create_payment endpoint requires a JWT token instead of an app-id and secret-key. This endpoint is designed for client-to-server calls, and the JWT is generated by Hello Clever’s servers. Refer to the v1 API reference for details.

​
Token expiry and refresh

The expires_in field in the token response is in seconds. When a token expires, repeat Step 2 to obtain a new one. Build your integration to handle 401 Unauthorized responses gracefully by refreshing the token and retrying the request.

​
Security best practices

Never embed your secret-key in client-side code, mobile apps, or any publicly accessible location. It must remain on your server at all times.
  • Store credentials in environment variables or a secrets manager, not in source code or configuration files checked into version control.
  • Rotate your secret-key periodically to limit the blast radius of a potential leak.
  • Use HTTPS for all API calls to ensure credentials and tokens are transmitted over an encrypted connection.
  • Scope access by creating separate linked sites (and therefore separate credentials) for different environments or applications.
  • Monitor for unexpected usage in the Merchant Portal to detect potential credential misuse early.