TrustRails

Overview

The TrustRails API uses API keys for authentication. Each request must include a valid API key in the Authorization header. This guide covers everything you need to know about managing and using your API keys securely.

Security First: API keys grant access to sensitive financial data. Treat them like passwords and never expose them in client-side code.

API Key Types

TrustRails provides three types of API keys, each designed for specific use cases:

Public Key (pk_)

Widget Only

Used exclusively for the TrustRails widget. Safe to include in frontend code.

tr_test_pk_abc123...

Secret Key (sk_)

Server Only

Used for server-side widget authentication. Exchange for a session token via the auth endpoint.

tr_test_sk_xyz789...

API Key (ak_)

Full API Access

Full access to the REST API. Create rollovers, query status, execute actions, and configure webhooks.

tr_test_ak_VG5oFY...

Environments

API keys are environment-specific. The key prefix indicates which environment it belongs to:

Environment	Prefix	Base URL	Use Case
Test / Sandbox	`tr_test_`	uat-api.trust-rails.com	Development & testing
Live / Production	`tr_live_`	api.trust-rails.com	Production transactions

Warning: Never use production (tr_live_) keys in development or test environments. Always use sandbox keys for testing.

Authentication Header

Include your API key in the Authorization header using the Bearer scheme:

curl -X GET "https://api.trust-rails.com/v1/rollovers" \
  -H "Authorization: Bearer tr_test_ak_YOUR_API_KEY" \
  -H "Content-Type: application/json"

Alternatively, you can use the X-API-Key header:

Bash

curl -X GET "https://api.trust-rails.com/v1/rollovers" \
  -H "X-API-Key: tr_test_ak_YOUR_API_KEY"

Key Rotation

Regular key rotation is a security best practice. To rotate your API key:

Generate a new API key in the Integration Portal
Update your application to use the new key
Verify the new key works correctly
Revoke the old key in the Integration Portal

Integration Portal showing how to revoke an old API key

Tip: We recommend rotating your API keys every 90 days. You can have multiple active keys simultaneously to allow for zero-downtime rotation.

Security Best Practices

Use Environment Variables

Never hardcode API keys in your source code. Use environment variables instead.

Bash

# .env file (never commit this!)
TRUSTRAILS_API_KEY=tr_test_ak_YOUR_API_KEY
# In your code
const apiKey = process.env.TRUSTRAILS_API_KEY;

Restrict Key Permissions

Only request the minimum permissions your application needs. If you only need to read rollover status, don't use a key with write permissions.

Monitor API Usage

Regularly review your API usage in the Integration Portal. Unusual patterns may indicate a compromised key.

Use IP Allowlisting

For production keys, consider enabling IP allowlisting to restrict which servers can use your API key.

Revoke Compromised Keys Immediately

If you suspect a key has been compromised (e.g., committed to a public repo), revoke it immediately in the Integration Portal and generate a new one.