Authentication

All requests to the TrustGate API must be authenticated. TrustGate supports multiple authentication methods depending on the use case: API keys for programmatic access, JWT tokens for dashboard sessions, and share tokens for public verification links.

Authentication Methods

Method	Header	Use Case
API Key	X-API-Key: sk_live_...	Server-to-server API calls, SDK access token generation
Bearer JWT	Authorization: Bearer your_token	Dashboard sessions (Auth0), developer portal tokens
Share Token	Token in request body	Public KYC verification links, attestation verification

Most integrations use API keys. JWT-based authentication is used internally by the TrustGate dashboard and developer portal. Share tokens are used for public-facing verification endpoints that do not require traditional authentication.

Dual Authentication on Primitives

The Primitives API (/api/v1/primitives/) accepts either an API key via X-API-Key or a Bearer JWT. If both are provided, the Bearer JWT takes precedence. This allows both dashboard users and API integrators to invoke primitives through the same endpoints.

API Key Types

TrustGate issues API keys with an environment prefix that determines their behavior:

Prefix	Environment	Behavior
sk_live_	Production	Real API calls, real verification providers, billed usage
sk_test_	Sandbox	Mock/test responses, no real provider calls, free usage

Keys are generated as sk_{environment}_{random_token} where the random portion is a 32-byte URL-safe token. Only the first 12 characters (the prefix) are stored for display purposes. The full key is hashed with SHA-256 and the hash is stored for authentication lookups.

The full API key is shown only once at creation time. It cannot be retrieved afterward. Store it securely immediately.

API Key Permissions

Each API key can be scoped with granular permissions:

Permission	Description
read:applicants	Read applicant data
write:applicants	Create and update applicants
read:documents	View uploaded documents
write:documents	Upload and manage documents
read:screening	View screening results
write:screening	Run screening checks and resolve hits
read:cases	View case data
write:cases	Create and manage cases
read:analytics	View analytics and usage data
invoke:primitives	Full access to all primitives
invoke:primitives.screening	Screening primitives only
invoke:primitives.biometrics	Biometrics primitives only
invoke:primitives.document	Document primitives only
invoke:primitives.device_intel	Device intel primitives only
invoke:primitives.ai	AI primitives only
invoke:primitives.storage	Storage primitives only

Permissions follow a hierarchy for primitive invocation:

• invoke:primitives grants access to all primitives.
• invoke:primitives.<category> grants access to all primitives within that category (e.g., invoke:primitives.screening covers screening.individual, screening.entity, etc.).
• A specific primitive ID can also be used: invoke:screening.individual.

Getting Your API Key

1. Log in to the TrustGate Dashboard.
2. Navigate to Integrations then API Keys (or Dev Workbench then API Keys).
3. Click Create API Key.
4. Provide a name, select the environment (live or test), choose permissions, and optionally set an expiration date.
5. Click Create. Copy and securely store the full key immediately.

You can also create keys programmatically:

curl -X POST https://api.bytrustgate.com/api/v1/integrations/api-keys \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Integration Key",
    "environment": "live",
    "permissions": ["read:applicants", "write:applicants", "invoke:primitives"]
  }'

Making Authenticated Requests

Using an API Key (X-API-Key header)

Most server-to-server integrations authenticate with the X-API-Key header:

cURL:

curl -X GET https://api.bytrustgate.com/api/v1/applicants \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json"

Python:

import requests

API_KEY = "sk_live_your_api_key_here"
BASE_URL = "https://api.bytrustgate.com/api/v1"

response = requests.get(
    f"{BASE_URL}/applicants",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
    },
)

data = response.json()

JavaScript (Node.js):

const API_KEY = "sk_live_your_api_key_here";
const BASE_URL = "https://api.bytrustgate.com/api/v1";

const response = await fetch(`${BASE_URL}/applicants`, {
  method: "GET",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
});

const data = await response.json();

Using a Bearer Token (Authorization header)

Dashboard sessions and developer portal tokens use the Authorization header with a Bearer prefix:

curl -X GET https://api.bytrustgate.com/api/v1/applicants \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json"

SDK Access Token Flow

For the embeddable Web SDK, your backend generates an access token using your API key, then your frontend uses that token:

# Step 1: Your backend requests an SDK access token
curl -X POST https://api.bytrustgate.com/api/v1/sdk/access-token \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_12345",
    "email": "user@example.com",
    "flow_name": "default",
    "redirect_url": "https://your-app.com/verification-complete",
    "expires_in": 3600
  }'

The response includes an sdk_url that your frontend redirects to or embeds in an iframe.

Tenant Isolation

Every authenticated request is automatically scoped to your tenant. TrustGate enforces tenant isolation at the database layer:

• API key requests: The API key is linked to your tenant_id. All queries are filtered to that tenant.
• JWT requests: The JWT token contains your tenant_id as a namespaced claim (https://bytrustgate.com/tenant_id). A database session is established with tenant context set, and all queries are filtered accordingly.
• Cross-tenant access is not possible. There is no mechanism to query or modify another tenant's data through the API.

This means you do not need to include a tenant identifier in your requests. The API key or JWT token determines which tenant's data you can access.

Rate Limiting

TrustGate enforces rate limits to protect service availability. Rate limiting is implemented using SlowAPI backed by Redis (or in-memory storage as a fallback).

Default Limits

Scope	Limit
Global default	200 requests per minute
SDK token creation	20 requests per minute
SDK verification start	20 requests per minute
Document uploads	10 requests per minute
Public attestation verification	60 requests per minute

Rate Limit Key

Rate limits are applied per authenticated user when a user ID is available in the request context. For unauthenticated requests, rate limits are applied per IP address.

Rate Limit Headers

When rate limiting is active, responses include standard headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait before retrying (on 429 responses)

When a rate limit is exceeded, the API returns HTTP 429 Too Many Requests:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "status": 429,
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Token-Based Public Access

Some TrustGate endpoints are designed for public access and use token-based authentication instead of API keys or JWTs. The token itself serves as both the identifier and the credential.

KYC Share Tokens

KYC share tokens allow third parties to verify an applicant's KYC status without having a TrustGate account. The token is passed in the request body to a public endpoint:

curl -X POST https://api.bytrustgate.com/api/v1/kyc-share/verify \
  -H "Content-Type: application/json" \
  -d '{
    "token": "share_token_value_here"
  }'

Share tokens have built-in security controls:

• Expiration: Tokens expire after a configured duration.
• Usage limits: Each token has a maximum number of uses (max_uses).
• Permission scoping: Tokens only expose the fields that were authorized when the token was created.
• Revocation: Tokens can be revoked at any time by the issuing tenant.
• Audit logging: Each verification attempt is logged with the requester's IP, domain, and user agent.

Attestation Verification

Attestation IDs can be verified publicly without any authentication. This allows anyone with an attestation ID (e.g., embedded in a PDF or shared link) to confirm its validity:

curl -X GET https://api.bytrustgate.com/api/v1/attestations/verify-attestation/{attestation_id}

This endpoint is rate-limited to 60 requests per minute per IP address.

Key Management

Revoking a Key

Revoked keys are immediately invalid for authentication:

curl -X DELETE https://api.bytrustgate.com/api/v1/integrations/api-keys/{key_id} \
  -H "Authorization: Bearer <your_jwt_token>"

Rotating a Key

Key rotation creates a new key with the same name and permissions, then revokes the old key in a single operation:

curl -X POST https://api.bytrustgate.com/api/v1/integrations/api-keys/{key_id}/rotate \
  -H "Authorization: Bearer <your_jwt_token>"

The response contains the new full key. The old key is immediately revoked.

Key Expiration

Keys can be created with an optional expires_at timestamp. Expired keys are rejected during authentication with an EXPIRED_API_KEY error code.

Security Best Practices

• Store API keys in environment variables or a secrets manager. Never hardcode them in source code.
• Never expose secret keys (sk_*) in client-side code. Use the SDK access token flow for frontend integrations.
• Use the minimum permissions necessary. Scope API keys to only the permissions your integration requires.
• Rotate keys periodically. Use the rotation endpoint to seamlessly replace keys.
• Monitor key usage. The API tracks last_used_at and last_used_ip for each key.
• Use test keys (sk_test_) during development. Switch to live keys only in production.
• Revoke compromised keys immediately. Revocation takes effect instantly.

---

Next Steps

• API Keys -- Detailed key management reference
• Error Handling -- Understanding API error responses
• Webhooks -- Real-time event notifications
• SDK Integration -- Embedding verification in your app