Skip to main content

​
Overview

TXCloud uses API keys to authenticate requests. All API requests must include your API key in the Authorization header using Bearer token authentication. 
Authorization: Bearer txc_live_your_api_key_here

​
API Key Types

TXCloud provides two types of API keys:
TypePrefixUse Case
Test/Sandboxtxc_test_Development and testing
Live/Productiontxc_live_Production applications
Never expose your API keys in client-side code. API keys should only be used in server-side applications.

​
Getting Your API Key

1

Log in to Dashboard

Go to dashboard.txcloud.io and sign in.
2

Navigate to API Keys

Click on Settings in the sidebar, then select API Keys.
3

Create New Key

Click Create API Key and configure:
  • Name: A descriptive name (e.g., “Production Server”)
  • Environment: Test or Live
  • Permissions: Select which APIs the key can access
  • IP Whitelist: (Optional) Restrict to specific IPs
4

Copy Your Key

Copy the key immediately — it won’t be shown again!

​
Making Authenticated Requests

import TXCloud from '@txcloud/sdk';

// The SDK handles authentication automatically
const txcloud = new TXCloud({
  apiKey: process.env.TXCLOUD_API_KEY
});

// All requests are automatically authenticated
const verification = await txcloud.identity.verify({
  document_front: '...',
  country: 'MA'
});

​
API Key Permissions

When creating an API key, you can restrict access to specific APIs:
PermissionDescription
identity:readRead verification results
identity:writeCreate new verifications
fraud:readRead fraud signals and analytics
fraud:writeConfigure fraud rules and blocklists
transactions:readRead transaction scores
transactions:writeScore transactions, update rules
lending:readRead credit assessments
lending:writeCreate assessments, upload statements
kyb:readRead business verifications
kyb:writeCreate business verifications
watchlist:readRead screening results
watchlist:writeScreen entities, manage lists
developers:readRead API usage and logs
developers:writeManage webhooks and settings
Follow the principle of least privilege — only grant the permissions each key needs.

​
IP Whitelisting

For additional security, you can restrict API keys to specific IP addresses: 
{
  "name": "Production API Key",
  "allowed_ips": [
    "203.0.113.50",
    "203.0.113.51",
    "10.0.0.0/8"  // CIDR notation supported
  ]
}
IP whitelisting is optional but recommended for production keys.

​
Key Rotation

We recommend rotating your API keys periodically:
1

Create New Key

Create a new API key with the same permissions.
2

Update Your Application

Deploy the new key to your application.
3

Verify New Key Works

Confirm requests are succeeding with the new key.
4

Revoke Old Key

Delete the old API key from the dashboard.
Revoking a key is immediate and irreversible. Ensure you’ve updated all applications first.

​
Required Headers

Every API request should include these headers:
HeaderRequiredDescription
AuthorizationYesBearer token with your API key
Content-TypeYes (POST/PUT)application/json
Idempotency-KeyRecommendedUnique key for safe retries
X-Request-IDOptionalYour request ID for tracing
curl -X POST https://api.txcloud.io/v1/identity/verify \
  -H "Authorization: Bearer txc_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "X-Request-ID: my-trace-id-456" \
  -d '{"document_front": "..."}'

​
Authentication Errors

Error CodeHTTP StatusDescription
unauthorized401Missing or invalid API key
forbidden403Key lacks required permissions
ip_not_allowed403Request from non-whitelisted IP
key_revoked401API key has been revoked
key_expired401API key has expired

​
Error Response Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "request_id": "req_a1b2c3d4"
  }
}

​
Best Practices

Store API keys in environment variables, not in code:
export TXCLOUD_API_KEY="txc_live_xxx"
Create separate keys for development, staging, and production.
Check the dashboard regularly for unusual activity.
Restrict production keys to known server IPs.
Rotate production keys every 90 days.

​
Next Steps

Rate Limits

Understand API rate limits

Error Handling

Handle errors gracefully