API Authentication

Overview

Calypso Public API uses API keys and request signatures for authentication.

To send API requests, create a public key and a secret key in the Calypso UI. The public key is sent in the Key header. The secret key is used only on the merchant side to create the request signature and must not be shared.

how-to-create-new-api-key.md

Required headers

Header	Required	Description
Key	Yes	Public API key.
Sign	Yes	HEX-encoded HMAC-SHA512 signature of the exact request body.
Content-Type	Yes	Must be application/json.

Request body requirements

Every API request body must be valid JSON and must include timestamp.

Field	Type	Required	Description
timestamp	number	Yes	Current Unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past or greater than 3 minutes in the future.

Account-scoped methods also include account, and methods with business parameters include payload. See each API method for its exact request body.

How to create a signature

1. Build the final JSON request body, including the current timestamp.
2. Convert the request body to the exact string that will be sent to Calypso.
3. Create an HMAC-SHA512 hash using the request body string as the message and the secret key as the key.
4. Convert the hash bytes to a lowercase hexadecimal string and send it in the Sign header.

Signature examples

JavaScript

const crypto = require("crypto-js");

function signature(body, secretKey) {
  return crypto.HmacSHA512(body, secretKey).toString(crypto.enc.Hex);
}

Python

import hashlib
import hmac


def signature(body, secret_key):
    return hmac.new(
        secret_key.encode(),
        body.encode(),
        hashlib.sha512
    ).hexdigest()

Timestamp examples

JavaScript

const timestamp = Date.now();

Python

import time

timestamp = round(time.time() * 1000)

Complete signing example

api_key = "c529e14832b34b74972365cf7bf02430"
secret_key = "b823a6b9ea72408583cef9ec8d67fa52"

body = '{"timestamp":1}'
sign = "b16e9d45f49f2069becbc4f108b237bee588cfc353fe9501df103e692acbc68d482a10d34c12bea22fedde7e28e1b8e57a6a0a373b0e9a27c5257bd8b36e13b9"

Handling unknown response fields

Calypso API may add new fields to responses without breaking existing integrations.

Requirement	Description
Ignore unknown response fields	API clients must continue processing a response even if it contains fields that are not used by the integration.
Do not use strict response schemas	Response parsing must allow additional fields.
Send only documented request fields	Unknown request fields can be rejected by API validation.

Related docs

Document	Link
Errors	Errors
Webhook signature check	Sign check