API Keys

API keys authenticate your requests to the TrustGate API. Manage keys securely to protect your integration and customer data.

Key Types

Secret Keys

Server-side keys with full API access:

Prefix	Environment	Use
tg_test_	Sandbox	Testing and development
tg_live_	Production	Live applications

Capabilities:

• Full API access
• Create and manage applicants
• Access verification results
• Configure settings

Security:

• Never expose in client-side code
• Store securely (environment variables, secrets manager)
• Rotate periodically

Public Keys

Client-side keys with limited access:

Prefix	Environment	Use
pk_test_	Sandbox	SDK testing
pk_live_	Production	SDK in production

Capabilities:

• Initialize SDK
• Start verification flows
• Upload documents (to assigned applicants only)

Security:

• Safe to expose in frontend code
• Cannot access other applicants' data
• Cannot modify settings

Creating API Keys

Via Dashboard

1. Go to Settings → API Keys
2. Click Create New Key
3. Select key type (Secret or Public)
4. Select environment (Sandbox or Production)
5. Add a description
6. Set permissions (optional)
7. Click Create

Via API

curl -X POST https://api.bytrustgate.com/v1/api-keys \
  -H "Authorization: Bearer tg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "secret",
    "environment": "production",
    "name": "Backend Server Key",
    "permissions": ["applicants:read", "applicants:write", "verifications:*"]
  }'

Response

{
  "id": "key_abc123",
  "type": "secret",
  "key": "tg_live_your_api_key_here",
  "environment": "production",
  "name": "Backend Server Key",
  "permissions": ["applicants:read", "applicants:write", "verifications:*"],
  "created_at": "2025-01-20T14:00:00Z"
}

Important: The full key is only shown once. Store it securely immediately.

Key Permissions

Available Permissions

Permission	Description
*	Full access (all permissions)
applicants:read	Read applicant data
applicants:write	Create/update applicants
documents:read	View documents
documents:write	Upload documents
verifications:read	View verification results
verifications:write	Trigger verifications
screening:read	View screening results
screening:write	Run screens, resolve hits
cases:read	View cases
cases:write	Create/manage cases
settings:read	View settings
settings:write	Modify settings
webhooks:*	Manage webhooks

Restricted Keys

Create keys with limited permissions:

curl -X POST https://api.bytrustgate.com/v1/api-keys \
  -H "Authorization: Bearer tg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "secret",
    "name": "Read-Only Analytics Key",
    "permissions": [
      "applicants:read",
      "verifications:read",
      "screening:read"
    ]
  }'

Using API Keys

HTTP Header

curl -X GET https://api.bytrustgate.com/v1/applicants \
  -H "Authorization: Bearer tg_live_xxx"

SDK Initialization

// Node.js
const TrustGate = require('@trustgate/sdk');

const client = new TrustGate({
  apiKey: process.env.TRUSTGATE_SECRET_KEY
});

# Python
from trustgate import Client

client = Client(api_key=os.environ['TRUSTGATE_SECRET_KEY'])

Frontend SDK

// Use public key only
TrustGate.init({
  publicKey: 'pk_live_xxx'
});

Managing Keys

List Keys

curl -X GET "https://api.bytrustgate.com/v1/api-keys" \
  -H "Authorization: Bearer tg_live_xxx"

Response

{
  "keys": [
    {
      "id": "key_abc123",
      "type": "secret",
      "prefix": "tg_live_...xyz",
      "name": "Backend Server Key",
      "permissions": ["*"],
      "last_used_at": "2025-01-20T14:30:00Z",
      "created_at": "2025-01-01T10:00:00Z"
    },
    {
      "id": "key_def456",
      "type": "public",
      "prefix": "pk_live_...abc",
      "name": "Web SDK Key",
      "last_used_at": "2025-01-20T14:35:00Z",
      "created_at": "2025-01-01T10:00:00Z"
    }
  ]
}

Revoke Key

curl -X DELETE "https://api.bytrustgate.com/v1/api-keys/key_abc123" \
  -H "Authorization: Bearer tg_live_xxx"

Rotate Key

Generate a new key and revoke the old one:

curl -X POST "https://api.bytrustgate.com/v1/api-keys/key_abc123/rotate" \
  -H "Authorization: Bearer tg_live_xxx"

Response

{
  "new_key": {
    "id": "key_ghi789",
    "key": "tg_live_your_new_key_here",
    "name": "Backend Server Key"
  },
  "old_key": {
    "id": "key_abc123",
    "revoked_at": "2025-01-20T15:00:00Z",
    "grace_period_ends": "2025-01-20T15:05:00Z"
  }
}

IP Restrictions

Restrict keys to specific IP addresses:

curl -X PATCH "https://api.bytrustgate.com/v1/api-keys/key_abc123" \
  -H "Authorization: Bearer tg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "ip_allowlist": [
      "192.168.1.0/24",
      "10.0.0.1"
    ]
  }'

Key Expiration

Set automatic expiration:

curl -X POST https://api.bytrustgate.com/v1/api-keys \
  -H "Authorization: Bearer tg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Temporary Integration Key",
    "expires_at": "2025-06-01T00:00:00Z"
  }'

Security Best Practices

Do's

• Use environment variables to store keys
• Use secrets managers (cloud secrets management, HashiCorp Vault)
• Rotate keys regularly (quarterly recommended)
• Use restricted permissions when possible
• Monitor key usage for anomalies
• Use different keys for different services

Don'ts

• Don't commit keys to source control
• Don't share keys via email or chat
• Don't use production keys in development
• Don't embed secret keys in mobile apps
• Don't log API keys in application logs

Example: Environment Variables

# .env file (never commit this)
TRUSTGATE_SECRET_KEY=tg_live_xxx
TRUSTGATE_PUBLIC_KEY=pk_live_xxx

// Node.js
require('dotenv').config();

const client = new TrustGate({
  apiKey: process.env.TRUSTGATE_SECRET_KEY
});

Key Usage Monitoring

View Key Activity

curl -X GET "https://api.bytrustgate.com/v1/api-keys/key_abc123/activity?period=7d" \
  -H "Authorization: Bearer tg_live_xxx"

Response

{
  "key_id": "key_abc123",
  "period": "7d",
  "activity": {
    "total_requests": 15420,
    "successful_requests": 15380,
    "failed_requests": 40,
    "unique_ips": 3,
    "endpoints_accessed": [
      {"endpoint": "/v1/applicants", "count": 5000},
      {"endpoint": "/v1/verifications", "count": 4500},
      {"endpoint": "/v1/screening/check", "count": 5920}
    ],
    "last_used_at": "2025-01-20T14:55:00Z",
    "last_used_ip": "192.168.1.100"
  }
}

---

Next Steps

• Webhooks - Set up event notifications
• SDK Integration - Client SDK guide
• Authentication API - Full auth reference