TrustRails

Overview

Every request to the TrustRails API must include a valid API key in the Authorization header (Bearer scheme) or the X-API-Key header. Keys are scoped by environment and type, so you can safely separate development from production.

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 and GraphQL 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:

You can rotate keys via the Integration Portal or programmatically via the API:

cURL

curl -X POST "https://api.trust-rails.com/v1/api-keys/rotate" \
  -H "Authorization: Bearer tr_test_ak_YOUR_CURRENT_KEY"

If you prefer the portal, follow these steps:

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

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;

Use the Right Key Type

Use the most restrictive key type for your use case. If you only need the widget, use a public key (pk_). Reserve API keys (ak_) for server-side integrations that need full access.

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.