Getting Your API Keys

Your API keys are used to authenticate your requests to the Trustist Ecommerce API. Keys are managed through the TrustistTransfer app and provide secure access to your resources.

⚠️ Important - Key Types: The Trustist API uses two types of keys with different capabilities:

Merchant Keys (self-service via TrustistTransfer app) - For payment operations only
Tenant Keys (requires contacting Trustist) - For customer and identity verification operations

See the Key Types section below for full details.

API Key Types

The Trustist Ecommerce API uses two distinct types of API keys, depending on what operations you need to perform:

1. Merchant Keys (Self-Service) 💳

What you can do:

✅ Process payments via the Payments API
✅ Create and manage standing orders
✅ Retrieve payment status
✅ Configure merchant payment webhooks

How to get them:

Log in to the TrustistTransfer app
Tap on the settings cog icon on the right-hand side of the lower navigation menu
Scroll down until you see the API Keys section

Scope: These keys are merchant-scoped and can only access payment operations for that specific merchant.

2. Tenant Keys (Contact Required) 🏢

What you can do:

✅ Create and manage customer records
✅ Initiate identity verification sessions (KYC/AML checks)
✅ Retrieve verification results
✅ Configure tenant identity verification webhooks
✅ Optionally also process payments (if configured)

How to get them:

📧 Contact Required: Tenant keys with customer and identity verification permissions are not yet self-service. Please contact Trustist support to request a tenant key with the specific permissions you need.

Scope: These keys are tenant-scoped and can access customer data and identity verification across all merchants under your tenant.

🚨 Common Mistake: If you try to use a merchant key (from TrustistTransfer app) to call customer or identity verification endpoints, you will receive a 403 Forbidden error. You must request a tenant key from Trustist support for these operations.

Which Key Do I Need?

If you want to...	You need...
Only process payments and standing orders	Merchant Key (self-service)
Perform KYC/AML checks on customers	Tenant Key (contact support)
Create and manage customer records	Tenant Key (contact support)
Both payments and identity verification	Tenant Key with payment permissions (contact support)

🔒 Security: Keep your API keys secure and never share them publicly. If you suspect a key has been compromised, regenerate it immediately (for merchant keys) or contact support (for tenant keys).

API Key Components

Both merchant and tenant keys consist of two parts, following Hawk authentication nomenclature:

Component	Description	Example
Hawk ID	A GUID that identifies your API key credential (safe to include in logs)	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`
Hawk Key	Shared secret used for request signing (never expose)	`sk_live_...`

Regenerating API Keys

For Merchant Keys:

Click the "Regenerate Keys" button in the API Keys section of the TrustistTransfer app
⚠️ Warning: This will immediately invalidate your previous keys
Update your applications with the new keys before proceeding

For Tenant Keys:

Contact Trustist support to request key regeneration
We'll coordinate the timing to minimize disruption to your integration

🚨 Important: Regenerating keys will break any existing integrations. Only regenerate when necessary for security reasons.

Next Steps

Once you have your API keys:

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

Continue to Authentication Setup →