API Keys

API keys are used to authenticate your requests to the Spell API. Each account can create up to 10 API key pairs.

An API key consists of two parts:

• API Key: The unique identifier of the key.
• API Secret: Used for request signing. This key is only displayed once upon creation, so please keep it safe.

🚨 Warning: Please treat your API Key and API Secret as confidential information. Never share them publicly or expose them in front-end code.

Authenticating with an API Key

When using the Spell API, you need to include your API Key in the X-API-Key request header, in the following format:

• X-API-Key: <Your API Key>

Here is an example using curl:

curl --request GET 
  --url https://api.spell.im/v1/account 
  --header 'X-API-Key: <Your API Key>'

Signing Your Requests

For APIs with a higher security level (e.g., POST requests), you need to sign your requests so that Spell can verify their security.

Signature Generation Rules

1. Prepare the Request Body: Add a timestamp parameter to the request body. Its value should be the current UNIX timestamp in milliseconds (e.g., 1698765432340), which is used to prevent replay attacks.
2. Serialization: Sort the request body, including the timestamp, in alphabetical order, and then serialize it into a string.
3. Calculate the Signature: Use your API Secret to perform an HMAC-SHA256 signature on the serialized string.

Including the Signature in the Request Header

Add the calculated signature to the X-Signature request header, in the following format:

• X-API-Key: <API Key>
• X-Signature: <SIGNATURE>

Here is an example using the crypto module in Node.js:

import * as crypto from 'crypto';

// Construct the data to be signed
const timestamp = Date.now();
const signedBody = { ...body, timestamp };
const serializedBodyString = serializeData(signedBody);
const xSignature = createSignature(serializedBodyString);

// The following are utility functions: serializeData() and createSignature()

/**
* Data Serialization
* @param data - Original data
* @returns The serialized data in the format: key1=value1&key2=value2...
*/
function serializeData(data: Record<string, any>): string {
    return Object.keys(data)
        .sort()
        .map(key => {
            const value = data[key];
            const strValue = typeof value === 'object'
                ? JSON.stringify(value)
                : String(value);
            return `${key}=${strValue}`;
        })
        .join('&');
}

/**
 * Calculates the signature
 * @param serializedData - The serialized data
 * @param secretKey - Your secret key
 * @returns The signature in hexadecimal format
 */
function calculateSignature(serializedData: string, secretKey: string): string {
    const hmac = crypto.createHmac('sha256', secretKey);
    hmac.update(serializedData);
    return hmac.digest('hex');
}

Sending a Signed Request

Here is a complete example of sending a POST request using curl:

curl --request POST 
  --url https://api.spell.im/v1/order/create 
  --header 'Content-Type: application/json' 
  --header 'X-API-Key: <Your API Key>' 
  --header 'X-Signature: 02b0c2a7134d1...' 
  --data '{
        "order_no": "A001", 
        "timestamp": 1698765432236,
        "timeout": 3600,
        ...
    }'