Quickstart

This guide will get you all set up and ready to use the API. We will cover the two authentication methods available, how to create API keys, and how to make your first API request.

Authentication Methods

The API supports two authentication methods depending on your use case:

User Authentication (Bearer Token)

Use this method when:

Building frontend applications
Users need to authenticate directly
You need user-specific data and operations

This method uses JWT tokens obtained through the authentication flow. Users authenticate with email and verification codes, then receive access and refresh tokens.

API Key Authentication (Cryptographic Signature)

Use this method when:

Making requests from your backend server
You cannot expose user tokens to your frontend
You need server-to-server communication

API keys use cryptographic signatures for secure authentication. Important: API keys are designed for backend use only. You cannot use them in frontend applications because they require a private key that must be kept secret.

Creating an API Key

API keys are created through the admin portal. Follow these steps:

Access the Admin Portal - Go to https://admin.crab3.xyz
Navigate to API Keys - Access the API Keys section in your admin dashboard
Create New API Key - Click "Add" or "Create" to create a new API key
Provide Details:
- Name - A descriptive name for your API key (e.g., "Production Server", "Staging Environment")
- Public Key - Your RSA public key in PEM format
- Whitelisted IPs (optional) - List of IP addresses allowed to use this API key
- Active - Whether the API key is active (default: true)

Generating RSA Key Pair

Before creating an API key, you need to generate an RSA key pair:

Generate RSA key pair

# Generate private key
openssl genrsa -out private_key.pem 2048

# Generate public key from private key
openssl rsa -in private_key.pem -pubout -out public_key.pem

# View public key (to copy for API key creation)
cat public_key.pem

Security Note: Keep your private key secure and never expose it. Only the public key should be submitted when creating an API key.

API Key Creation Example

When creating an API key through the admin portal, you'll provide:

{
  "name": "My Backend Server",
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...\n-----END PUBLIC KEY-----",
  "whitelistedIps": ["192.168.1.100", "10.0.0.50"],
  "active": true
}

After creation, you'll receive an API key ID that you'll use in requests.

Using API Key Authentication

API key authentication requires several headers and a cryptographic signature. Here's how it works:

Required Headers

Every request using API key authentication must include:

x-tenant-id - Your tenant identifier
x-client-id - The client ID associated with the API key
x-api-key - Your API key ID (received when creating the key)
x-api-timestamp - Current timestamp in milliseconds (Unix epoch)
x-api-signature - Cryptographic signature (base64 encoded)

Creating the Signature

The signature is created by signing a string composed of:

stringToSign = timestamp + method + originalUrl + bodyString

Where:

timestamp - Same value as x-api-timestamp header
method - HTTP method (GET, POST, PUT, etc.)
originalUrl - Full request path including query parameters
bodyString - JSON stringified request body (empty string for GET requests)

The signature is created using:

Algorithm: SHA256
Key: Your RSA private key (corresponding to the public key you registered)
Encoding: Base64

Example: Making a Request with API Key

Here's a complete example of making a request with API key authentication:

Example: Get wallet with API key

# 1. Set variables
TIMESTAMP=$(date +%s%3N)  # Current timestamp in milliseconds
METHOD="GET"
URL="/api/wallet"
BODY=""  # Empty for GET requests
STRING_TO_SIGN="${TIMESTAMP}${METHOD}${URL}${BODY}"

# 2. Create signature (using your private key)
SIGNATURE=$(echo -n "$STRING_TO_SIGN" | openssl dgst -sha256 -sign private_key.pem | base64 -w 0)

# 3. Make request
curl -X GET https://api.example.com/api/wallet \
  -H "x-tenant-id: {tenant-id}" \
  -H "x-client-id: {client-id}" \
  -H "x-api-key: {api-key-id}" \
  -H "x-api-timestamp: ${TIMESTAMP}" \
  -H "x-api-signature: ${SIGNATURE}"

Example: POST Request with Body

For POST requests, include the request body in the signature:

Example: Create wallet with API key

# 1. Set variables
TIMESTAMP=$(date +%s%3N)
METHOD="POST"
URL="/api/wallet"
BODY='{}'  # JSON body
STRING_TO_SIGN="${TIMESTAMP}${METHOD}${URL}${BODY}"

# 2. Create signature
SIGNATURE=$(echo -n "$STRING_TO_SIGN" | openssl dgst -sha256 -sign private_key.pem | base64 -w 0)

# 3. Make request
curl -X POST https://api.example.com/api/wallet \
  -H "x-tenant-id: {tenant-id}" \
  -H "x-client-id: {client-id}" \
  -H "x-api-key: {api-key-id}" \
  -H "x-api-timestamp: ${TIMESTAMP}" \
  -H "x-api-signature: ${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d '{}'

Timestamp Validation

The API validates that request timestamps are within 1 minute of the server time. This prevents replay attacks. Make sure your server clock is synchronized (consider using NTP).

If the timestamp is too old or too far in the future, you'll receive:

{
  "status": 401,
  "message": "Request timestamp is too old or too far in the future."
}

IP Whitelisting

If you configured IP whitelisting when creating your API key, only requests from those IP addresses will be accepted. The API checks the x-forwarded-for header or the connection's remote address.

If your IP is not whitelisted, you'll receive:

{
  "status": 403,
  "message": "IP address not allowed."
}

When to Use Each Method

Use Bearer Token (User Authentication) When:

✅ Building frontend applications
✅ Users authenticate directly in your app
✅ You need user-specific operations (view their wallet, make transfers, etc.)
✅ You can securely store tokens in your frontend

Use API Key When:

✅ Making requests from your backend server
✅ You cannot expose user authentication tokens
✅ You need to perform operations on behalf of users server-side
✅ You're building server-to-server integrations

Important: API keys require a private key that must be kept secret. Never expose your private key in frontend code, client-side applications, or public repositories.

Making Your First Request

Using Bearer Token (User Authentication)

First, complete the authentication flow to get an access token:

Get access token

# 1. Login
curl -X POST https://api.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "email": "user@example.com",
    "password": "password"
  }'

# 2. Verify code (received via email)
curl -X POST https://api.example.com/api/auth/verify-code \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "email": "user@example.com",
    "code": "123456"
  }'

# 3. Use access token
curl -X GET https://api.example.com/api/wallet \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Using API Key (Backend)

Get wallet with API key

TIMESTAMP=$(date +%s%3N)
METHOD="GET"
URL="/api/wallet"
BODY=""
STRING_TO_SIGN="${TIMESTAMP}${METHOD}${URL}${BODY}"
SIGNATURE=$(echo -n "$STRING_TO_SIGN" | openssl dgst -sha256 -sign private_key.pem | base64 -w 0)

curl -X GET https://api.example.com/api/wallet \
  -H "x-tenant-id: {tenant-id}" \
  -H "x-client-id: {client-id}" \
  -H "x-api-key: {api-key-id}" \
  -H "x-api-timestamp: ${TIMESTAMP}" \
  -H "x-api-signature: ${SIGNATURE}"

What's Next?

Now that you understand authentication, here are the next steps:

Learn about authentication flows - Complete guide to user authentication
Create your wallet - Set up your smart contract wallet
Complete KYC verification - Verify your identity
Explore available endpoints - See all available API endpoints

Security Best Practices

Keep Private Keys Secret - Never commit private keys to version control or expose them in frontend code
Use Environment Variables - Store sensitive credentials in environment variables
Rotate Keys Regularly - Periodically rotate your API keys for better security
Use IP Whitelisting - Restrict API key usage to specific IP addresses when possible
Monitor Usage - Regularly check API key usage and revoke unused keys
Sync Server Time - Ensure your server clock is synchronized to avoid timestamp errors
Validate Signatures - Always validate signatures on your end before making requests