Authentication

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:

Type	Prefix	Use Case
Test/Sandbox	`txc_test_`	Development and testing
Live/Production	`txc_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

Go to dashboard.txcloud.io and sign in.

Navigate to API Keys

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

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

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'
});

from txcloud import TXCloud
import os

# Initialize with your API key
txcloud = TXCloud(api_key=os.environ.get("TXCLOUD_API_KEY"))

# All requests are automatically authenticated
verification = txcloud.identity.verify(
    document_front="...",
    country="MA"
)

# Include the Authorization header in every request
curl -X POST https://api.txcloud.io/v1/identity/verify \
  -H "Authorization: Bearer txc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"document_front": "...", "country": "MA"}'

import "github.com/txcloud/txcloud-go"

client := txcloud.NewClient(os.Getenv("TXCLOUD_API_KEY"))

verification, err := client.Identity.Verify(&txcloud.VerifyRequest{
    DocumentFront: "...",
    Country: "MA",
})

API Key Permissions

When creating an API key, you can restrict access to specific APIs:

Permission	Description
`identity:read`	Read verification results
`identity:write`	Create new verifications
`fraud:read`	Read fraud signals and analytics
`fraud:write`	Configure fraud rules and blocklists
`transactions:read`	Read transaction scores
`transactions:write`	Score transactions, update rules
`lending:read`	Read credit assessments
`lending:write`	Create assessments, upload statements
`kyb:read`	Read business verifications
`kyb:write`	Create business verifications
`watchlist:read`	Read screening results
`watchlist:write`	Screen entities, manage lists
`developers:read`	Read API usage and logs
`developers:write`	Manage 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:

Create New Key

Create a new API key with the same permissions.

Update Your Application

Deploy the new key to your application.

Verify New Key Works

Confirm requests are succeeding with the new key.

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:

Header	Required	Description
`Authorization`	Yes	Bearer token with your API key
`Content-Type`	Yes (POST/PUT)	`application/json`
`Idempotency-Key`	Recommended	Unique key for safe retries
`X-Request-ID`	Optional	Your 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 Code	HTTP Status	Description
`unauthorized`	401	Missing or invalid API key
`forbidden`	403	Key lacks required permissions
`ip_not_allowed`	403	Request from non-whitelisted IP
`key_revoked`	401	API key has been revoked
`key_expired`	401	API key has expired

Error Response Example

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

Best Practices

Use Environment Variables

Store API keys in environment variables, not in code:

export TXCLOUD_API_KEY="txc_live_xxx"

Use Different Keys per Environment

Create separate keys for development, staging, and production.

Monitor Key Usage

Check the dashboard regularly for unusual activity.

Enable IP Whitelisting

Restrict production keys to known server IPs.

Rotate Keys Regularly

Rotate production keys every 90 days.

Next Steps

Rate Limits

Understand API rate limits

Error Handling

Handle errors gracefully

Getting Started

Core Concepts

Guides

SDKs

Resources

Overview

API Key Types

Getting Your API Key

Making Authenticated Requests

API Key Permissions

IP Whitelisting

Key Rotation

Required Headers

Authentication Errors

Error Response Example

Best Practices

Next Steps

Rate Limits

Error Handling

​Overview

​API Key Types

​Getting Your API Key

​Making Authenticated Requests

​API Key Permissions

​IP Whitelisting

​Key Rotation

​Required Headers

​Authentication Errors

​Error Response Example

​Best Practices

​Next Steps

Rate Limits

Error Handling

Overview

API Key Types

Getting Your API Key

Making Authenticated Requests

API Key Permissions

IP Whitelisting

Key Rotation

Required Headers

Authentication Errors

Error Response Example

Best Practices

Next Steps