API Authentication Guide

The API uses dual authentication for business operations: both Bearer Token and API Key Signatures are required. Here's how to set it up:

Prerequisites

OpenSSL (pre-installed on macOS/Linux)
curl (command-line HTTP client)
jq (recommended for JSON processing)

Step 1: Get Your Bearer Token

Obtain a Bearer token (required for ALL operations):

curl -X POST https://ramp.transfero.tools/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

🔑 Save this token - you'll need it for ALL API requests.

Step 2: Generate RSA Key Pair

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

# Extract public key
openssl rsa -in private_key.pem -pubout -out public_key.pem

⚠️ Keep private_key.pem secure - never share it!

Step 3: Register Your API Key

Choose a key name and sign it:

KEY_NAME="MyProductionKey"
printf "%s" "$KEY_NAME" | openssl dgst -sha256 -sign private_key.pem -out signature.bin
SIGNATURE_B64=$(openssl base64 -in signature.bin -A)

Create registration payload:

# Using jq (recommended)
jq -n \
  --arg name "$KEY_NAME" \
  --arg publicKey "$(cat public_key.pem)" \
  --arg signature "$SIGNATURE_B64" \
  '{name: $name, publicKey: $publicKey, signature: $signature}' \
  > payload.json

Register the key:

curl -X POST https://ramp.transfero.tools/v1/api-keys \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d @payload.json

Success Response:

{
  "message": "API key registered successfully",
  "apiKey": "abc123def456...",
  "name": "MyProductionKey"
}

🔑 Save the apiKey value - this is your key hash for all future requests.

Step 4: Making Authenticated Requests

Every business API request needs BOTH authentication methods:

Required Headers:

Authorization: Bearer YOUR_TOKEN (user authentication)
X-API-Key: Your key hash from registration
X-API-Timestamp: Current timestamp in milliseconds
X-API-Signature: Signed request details

Signature Format:

{timestamp}{HTTP_METHOD}{path}{body}

Example: Create a Client

#!/bin/bash

# Configuration
API_KEY_HASH="abc123def456..."  # From registration
BEARER_TOKEN="your_bearer_token_here"  # From Step 1
BASE_URL="https://ramp.transfero.tools"

# Request details
TIMESTAMP_MS=$(($(date +%s%N)/1000000))
REQUEST_METHOD="POST"
REQUEST_PATH="/v1/clients/"
REQUEST_BODY='{"name":"João Silva","email":"[email protected]","tax_id":"12345678901"}'

# Create signature content
CONTENT_TO_SIGN="${TIMESTAMP_MS}${REQUEST_METHOD}${REQUEST_PATH}${REQUEST_BODY}"

# Generate signature
printf "%s" "$CONTENT_TO_SIGN" | openssl dgst -sha256 -sign private_key.pem -out request_signature.bin
REQUEST_SIGNATURE=$(openssl base64 -in request_signature.bin -A)

# Make request
curl -X POST "${BASE_URL}${REQUEST_PATH}" \
  -H "Authorization: Bearer ${BEARER_TOKEN}" \
  -H "X-API-Key: ${API_KEY_HASH}" \
  -H "X-API-Timestamp: ${TIMESTAMP_MS}" \
  -H "X-API-Signature: ${REQUEST_SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d "$REQUEST_BODY"

# Clean up
rm -f request_signature.bin

Example: List Clients (GET)

#!/bin/bash

# Request details (no body for GET)
TIMESTAMP_MS=$(($(date +%s%N)/1000000))
REQUEST_METHOD="GET"
REQUEST_PATH="/v1/clients/"
REQUEST_BODY=""

# Create signature content
CONTENT_TO_SIGN="${TIMESTAMP_MS}${REQUEST_METHOD}${REQUEST_PATH}${REQUEST_BODY}"

# Generate signature
printf "%s" "$CONTENT_TO_SIGN" | openssl dgst -sha256 -sign private_key.pem -out request_signature.bin
REQUEST_SIGNATURE=$(openssl base64 -in request_signature.bin -A)

# Make request
curl -X GET "${BASE_URL}${REQUEST_PATH}" \
  -H "Authorization: Bearer ${BEARER_TOKEN}" \
  -H "X-API-Key: ${API_KEY_HASH}" \
  -H "X-API-Timestamp: ${TIMESTAMP_MS}" \
  -H "X-API-Signature: ${REQUEST_SIGNATURE}"

# Clean up
rm -f request_signature.bin

Complete Registration Script

Here's a complete script that handles everything:

#!/bin/bash
set -e

# Configuration
KEY_NAME="MyProductionKey"
BEARER_TOKEN="your_bearer_token_here"

echo "🔐 Generating RSA key pair..."
openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem

echo "✍️ Signing key name..."
printf "%s" "$KEY_NAME" | openssl dgst -sha256 -sign private_key.pem -out signature.bin
SIGNATURE_B64=$(openssl base64 -in signature.bin -A)

echo "📝 Creating JSON payload..."
jq -n \
  --arg name "$KEY_NAME" \
  --arg publicKey "$(cat public_key.pem)" \
  --arg signature "$SIGNATURE_B64" \
  '{name: $name, publicKey: $publicKey, signature: $signature}' \
  > payload.json

echo "🚀 Registering API key..."
RESPONSE=$(curl -s -X POST https://ramp.transfero.tools/v1/api-keys \
     -H "Authorization: Bearer $BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d @payload.json)

echo "📄 Response: $RESPONSE"

if echo "$RESPONSE" | grep -q "API key registered successfully"; then
    echo "✅ Success! Extract your API key hash from the response above."
else
    echo "❌ Registration failed. Check the response for details."
fi

# Clean up
rm -f signature.bin payload.json
echo "🔒 Keep your private_key.pem secure!"

Authentication Summary

Operation	Bearer Token	API Signature	Example
API Key Management	✅ Required	❌ Not needed	`POST /v1/api-keys`
Business Operations	✅ Required	✅ Required	`POST /v1/clients/`

All business endpoints require BOTH Bearer token AND API key signature!

Troubleshooting

"Invalid signature"

Check your signature content format matches exactly
Ensure no extra whitespace in the content string
Verify your private/public key pair
Important: Use printf "%s" instead of echo -n for signature generation

"Timestamp errors"

Timestamps must be within 15 minutes of server time
Use milliseconds: $(($(date +%s%N)/1000000))

"Duplicate key errors"

Each public key can only be registered once
Use a different key name or generate new keys

Ready to Use

You're now ready to make authenticated requests with both Bearer token and API signatures to create clients, process transactions, and access all business endpoints!