Authentication

{
    "success": false,
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Invalid API key or appId",
        "timestamp": "2024-01-15T10:30:00.000Z",
        "requestId": "req_123e4567-e89b-12d3-a456-426614174000"
    }
}

Authentication Headers

Header	Required	Format	Description
`apiKey`	Yes	`xf_` prefixed string	Your unique API key
`appId`	Yes	UUID format	Your application identifier

Getting Your API Credentials

Log into Dashboard

Navigate to dashboard.xentfi.com and log in.

Go to API Keys

Click Settings → API Keys in the left sidebar.

Generate New Key

Click Generate New API Key, enter a name, and select environment.

Copy Credentials

Copy your apiKey and appId. Store them securely - you won’t see the key again!

Making Authenticated Requests

Include both headers in every API request:

curl -X GET https://api.xentfi.com/v1/master-wallets \
  -H "apiKey: xf_abc123def456..." \
  -H "appId: app_123e4567-e89b-12d3-a456-426614174000"

fetch('https://api.xentfi.com/v1/master-wallets', {
  headers: {
    'apiKey': 'xf_abc123def456...',
    'appId': 'app_123e4567-e89b-12d3-a456-426614174000'
  }
});

import requests

headers = {
    'apiKey': 'xf_abc123def456...',
    'appId': 'app_123e4567-e89b-12d3-a456-426614174000'
}

response = requests.get('https://api.xentfi.com/v1/master-wallets', headers=headers)

Authentication Response

Success (200)

When authentication succeeds, you receive the requested data.

Failure (401)

When authentication fails:

{
    "success": false,
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Invalid API key or appId",
        "timestamp": "2024-01-15T10:30:00.000Z",
        "requestId": "req_123e4567-e89b-12d3-a456-426614174000"
    }
}

API Key Types

Type	Environment	Use Case
Sandbox	Testnet	Development and testing
Production	Mainnet	Live transactions

Sandbox Keys

Use for development and testing
Testnet networks only
Higher rate limits
No real funds required

Production Keys

Use for live transactions
Mainnet networks only
Standard rate limits
Real funds transfer

API Key Scopes

Scope	Permissions	Use Case
`read`	GET endpoints only	Monitoring, analytics
`write`	POST, PUT, DELETE	Full API access
`admin`	All operations + admin	Account management

Security Best Practices

Never share your API keys publicly. Always use environment variables.

Practice	Importance	Description
Environment variables	Critical	Never hardcode keys in code
Regular rotation	High	Rotate keys every 90 days
Environment separation	High	Different keys for dev/prod
Least privilege	High	Grant minimum required scopes
Immediate revocation	Critical	Revoke compromised keys immediately
Audit logging	Medium	Monitor key usage

Key Rotation

When to Rotate

Every 90 days (recommended)
Team member departure
Suspected compromise
Security audit requirement

Rotation Process

Rotating via API

curl -X POST https://api.xentfi.com/v1/api-keys/{keyId}/rotate \
  -H "apiKey: current-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json"

Key Revocation

If a key is compromised, revoke it immediately:

curl -X DELETE https://api.xentfi.com/v1/api-keys/{keyId} \
  -H "apiKey: your-admin-key" \
  -H "orgId: your-org-id"

Environment Setup

Development Environment (.env)

# Sandbox Environment
XENTFI_API_KEY=xf_sandbox_abc123...
XENTFI_ORG_ID=orgId__123e4567...
XENTFI_ENVIRONMENT=sandbox
XENTFI_BASE_URL=https://api.xentfi.com/v1

Production Environment

# Production Environment
XENTFI_API_KEY=xf_prod_xyz789...
XENTFI_ORG_ID=aorgId_789abc...
XENTFI_ENVIRONMENT=production
XENTFI_BASE_URL=https://api.xentfi.com/v1

Troubleshooting

401 Unauthorized - Invalid API key

Possible causes:

API key is incorrect
API key has been revoked
Using sandbox key on production

Solutions:

Verify API key in dashboard
Generate new key if needed
Check environment matching

401 Unauthorized - Missing headers

Solution: Ensure both apiKey and appId headers are included in every request.

403 Forbidden - Insufficient scope

Solution: Your API key doesn’t have permission for this operation. Generate a key with required scopes.

Rate Limits by Key Type

Key Type	Requests/Second	Requests/Minute	Requests/Day
Sandbox (Starter)	5	60	10,000
Sandbox (Pro)	20	300	100,000
Production (Starter)	5	60	10,000
Production (Pro)	20	300	100,000
Production (Business)	50	1,000	1,000,000

Rate Limits Guide - Detailed rate limit information
Error Handling - Common authentication errors
Security Overview - Security best practices

API Introduction Error Handling

Getting Started

Addresses

Auto Settlement

Transfer

AML

Assets

Prices

Master Wallets

Payment Links

Signing

Webhooks

Authentication Headers

Getting Your API Credentials

Making Authenticated Requests

Authentication Response

Success (200)

Failure (401)

API Key Types

Sandbox Keys

Production Keys

API Key Scopes

Security Best Practices

Key Rotation

When to Rotate

Rotation Process

Rotating via API

Key Revocation

Environment Setup

Development Environment (.env)

Production Environment

Troubleshooting

Rate Limits by Key Type

​Authentication Headers

​Getting Your API Credentials

​Making Authenticated Requests

​Authentication Response

​Success (200)

​Failure (401)

​API Key Types

​Sandbox Keys

​Production Keys

​API Key Scopes

​Security Best Practices

​Key Rotation

​When to Rotate

​Rotation Process

​Rotating via API

​Key Revocation

​Environment Setup

​Development Environment (.env)

​Production Environment

​Troubleshooting

​Rate Limits by Key Type

​Related Resources

Authentication Headers

Getting Your API Credentials

Making Authenticated Requests

Authentication Response

Success (200)

Failure (401)

API Key Types

Sandbox Keys

Production Keys

API Key Scopes

Security Best Practices

Key Rotation

When to Rotate

Rotation Process

Rotating via API

Key Revocation

Environment Setup

Development Environment (.env)

Production Environment

Troubleshooting

Rate Limits by Key Type

Related Resources