Getting Your API Keys

Your API keys authenticate requests to the Trustist Ecommerce API. Trustist issues TE API keys for your integration and configures each key with the permissions your application needs.

API access is permission based. You do not need to choose between different internal key classes. Use the API key issued for your product, and make sure it has the permissions required by the endpoints you call.

How API Access Works

A TE API key identifies your organisation and controls which API operations are available to your application. The same integration may use payments, customer management, onboarding, AIS, payouts, or webhooks, depending on how the key has been configured.

Getting a Key

Request TE API access

Contact Trustist to request API credentials for the environments you need, such as sandbox and production. Trustist will issue a Hawk ID and Hawk Key and configure the permissions for your use case.

Tell us what your integration will use

Your key can be configured for TE capabilities such as payments, customer records, identity verification, AIS, payouts, merchant bank account access, and webhooks. If the scope changes later, contact Trustist to update the key permissions.

Common Permissions

  • create_payment, read_payment - Create payments and retrieve payment status
  • create_standing_order, read_standing_order - Create and manage standing orders
  • create_customer, read_customers, update_customer - Manage customer records
  • create_onboard_session, read_onboard_session, read_onboard_results - Run KYC, AML, and onboarding checks
  • read_customer_bank_accounts, read_customer_bank_account_balances, read_customer_bank_account_transactions - Access AIS bank data
  • create_payout, read_payout, approve_payout - Create, view, and approve payouts
  • manage_webhooks - Register and manage webhook endpoints

If you receive a 403 Forbidden response, your key is valid but is not configured for the requested operation. Contact Trustist support if the permission should be enabled.

Merchant Context

Some operations need to know which merchant account they apply to, especially payments, payouts, merchant bank accounts, and AIS flows that are tied to a receiving merchant. If your API access can operate across more than one merchant, include the merchant identifier supplied by Trustist in the X-Trustist-MerchantId header.

Ambiguous merchant context: If a request needs a merchant and the API cannot determine one from your credentials or headers, it will reject the request instead of guessing. Add X-Trustist-MerchantId or contact support to confirm the correct setup.

Which Access Do I Need?

If you want to... Your API key needs...
Only process payments and standing orders Payment and standing order permissions for the merchant being paid
Perform KYC/AML checks on customers Customer and onboard session permissions
Create and manage customer records Customer management permissions
Both payments and identity verification Payment, customer, and onboard session permissions
Security: Keep your API keys secure and never share them publicly. If you suspect a key has been compromised, contact Trustist support to rotate it.

API Key Components

Each API key consists of two parts, following Hawk authentication nomenclature:

Component Description Example
Hawk ID A GUID that identifies your API key credential. This is safe to include in logs. a1b2c3d4-e5f6-7890-abcd-ef1234567890
Hawk Key Shared secret used for request signing. Never expose this value. sk_live_...

Regenerating API Keys

TE API keys:

  • Contact Trustist support to request key regeneration
  • We'll coordinate the timing to minimize disruption to your integration
  • Update your applications with the new key before the old key is disabled
Important: Regenerating keys will break any existing integrations. Only regenerate when necessary for security reasons.

Next Steps

Once you have your API keys:

  1. Set up your development environment
  2. Configure authentication in your application
  3. Test your integration using our sandbox environment
  4. Go live with production keys when ready

Continue to Authentication Setup ->