# 🔑 API Key Authentication Guide

This guide walks you through setting up secure API key authentication for the Ramp Transfero Tools API. You'll generate an RSA key pair, register it, and use it to sign your requests.

# 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):

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

**Response:**

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

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

## Step 2: Generate RSA Key Pair

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
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:**

```json
{
  "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

```bash
#!/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":"joao@example.com","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)

```bash
#!/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:

```bash
#!/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!