Authentication

Authentication API

All REALM AI API requests must be authenticated. We primarily use API Key authentication, with optional signature-based authentication for sensitive operations.

Base URL

https://api.realm.ai/v1

Authentication Methods

1. API Key Authentication (Standard)

Include your API Key in the X-API-Key HTTP header for all requests.

Example:

GET /v1/user/profile HTTP/1.1
Host: api.realm.ai
X-API-Key: YOUR_API_KEY

2. Signature Authentication (Enhanced Security)

For sensitive endpoints (e.g., initiating marketplace transactions, modifying critical settings), an additional signature is required.

1. Construct the String to Sign: Concatenate the following, separated by newlines ():

   • HTTP Method (e.g., POST)

   • Request Path (e.g., /v1/marketplace/listings)

   • Timestamp (Unix timestamp in seconds, included as X-Timestamp header)

   • Request Body (if present, otherwise empty string)

2. Generate Signature: Create an HMAC-SHA256 hash of the string using your API Secret as the key. Encode the hash in Base64.

3. Include Headers: Add the following headers to your request:

   • X-API-Key: Your API Key

   • X-Timestamp: The Unix timestamp used in step 1.

   • X-Signature: The Base64 encoded HMAC-SHA256 signature from step 2.

Example (Conceptual Python):

import time
import hmac
import hashlib
import base64

api_secret = "YOUR_API_SECRET"
api_key = "YOUR_API_KEY"

method = "POST"
path = "/v1/marketplace/listings"
timestamp = str(int(time.time()))
body = '{"modelId": "model_123", "price": 10.5}' # Example body

string_to_sign = f"{method}\n{path}\n{timestamp}\n{body}"

signature = base64.b64encode(hmac.new(
    api_secret.encode('utf-8'),
    string_to_sign.encode('utf-8'),
    hashlib.sha256
).digest()).decode('utf-8')

headers = {
    'X-API-Key': api_key,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
    'Content-Type': 'application/json'
}

# Now make the request with these headers and body

Endpoints requiring signature authentication will be clearly marked in their respective documentation sections.

Error Handling

• 401 Unauthorized: Missing or invalid X-API-Key.

• 403 Forbidden: Invalid signature or timestamp for endpoints requiring signature authentication.

Ensure your server clock is synchronized with NTP for accurate timestamps.