Authentication

Every request to the Sotto API is authenticated with an HMAC-SHA256 signature. Sotto issues each vendor a username and a secret; the secret is used to sign requests and is never transmitted.

Required headers

string

required

The vendor username tied to your API secret.

string

required

The Base64-encoded HMAC-SHA256 signature of the request. See Generating the signature.

string

required

The time the request is sent, in ISO 8601 UTC format (e.g. 2024-03-05T17:52:11.345Z). This must match the value used when generating the signature.

string

Must be application/json for JSON requests, or multipart/form-data for file uploads.

string

The Base64-encoded request body. Required for POST and PUT requests.

Generating the signature

The signature is computed as:

x-bigco-hmac-sha256 = Base64( HMAC-SHA256( API_SECRET, StringToSign ) )

The StringToSign differs by method.

x-date: {x_date}
{REQUEST_METHOD} {url_path_and_query}

x-date: {x_date}
{REQUEST_METHOD} {url_path_and_query}
x-digest: {body_base64}

string

The request timestamp in ISO 8601 format. Must match the x-date header.

string

The HTTP method in uppercase (GET, POST, PUT, DELETE).

string

The request path and query string after the domain — for example, /api/v1/users?phone_number=+15551234567.

string

The Base64 encoding of the request body. The JSON keys must be sorted alphabetically and all whitespace and newlines removed before encoding.

The body used to compute x-digest must be serialized with keys sorted alphabetically and no extra whitespace (equivalent to json.dumps(body, sort_keys=True, separators=(",", ":"))). A signature computed over differently-formatted JSON will fail verification.

Step by step

Retrieve your secret

Load the API_SECRET issued to you by Sotto.

Capture the timestamp

Generate the current time in ISO 8601 UTC format and use it for both the signature and the x-date header.

Encode the body

For POST/PUT, sort the JSON keys alphabetically, strip whitespace, and Base64-encode the result to produce x-digest.

Build the string to sign

Assemble the StringToSign using the timestamp, method, path with query, and (for POST/PUT) the Base64 body.

Sign and send

Compute the HMAC-SHA256 signature with your secret, then send the request with the x-bigco-hmac-username, x-bigco-hmac-sha256, x-date, and (for POST/PUT) x-digest headers.

Example

const CryptoJS = require('crypto-js');

// Retrieve the secret.
const secret = pm.environment.get('api_secret');

// Obtain the current time.
const x_date = new Date().toISOString();

// Convert the body to Base64.
const body = pm.request.body.raw || '';
const body_base64 = Buffer.from(body, 'utf-8').toString('base64');

const method = pm.request.method;
const path_and_parameters = pm.request.url.getPathWithQuery();

// Construct the string to sign.
let signing_string = `x-date: ${x_date}\n${method} ${path_and_parameters}`;
if (body_base64 !== '') {
  signing_string += `\nx-digest: ${body_base64}`;
  pm.request.headers.add({ key: 'x-digest', value: body_base64 });
}

// Generate the signature.
const signature = CryptoJS.enc.Base64.stringify(
  CryptoJS.HmacSHA256(CryptoJS.enc.Utf8.parse(signing_string), secret)
);

// Set the headers.
pm.request.headers.add({ key: 'x-date', value: x_date });
pm.request.headers.add({ key: 'x-bigco-hmac-sha256', value: signature });
pm.request.headers.add({ key: 'x-bigco-hmac-username', value: pm.environment.get('api_username') });
pm.request.headers.add({ key: 'content-type', value: 'application/json' });

import base64
import hashlib
import hmac
import json
from datetime import datetime, timezone

def sign_request(secret, method, path_and_query, body=None):
    x_date = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
    string_to_sign = f"x-date: {x_date}\n{method.upper()} {path_and_query}"

    headers = {
        "x-date": x_date,
        "x-bigco-hmac-username": "YOUR_USERNAME",
        "content-type": "application/json",
    }

    if body is not None:
        canonical = json.dumps(body, sort_keys=True, separators=(",", ":"))
        body_base64 = base64.b64encode(canonical.encode()).decode()
        string_to_sign += f"\nx-digest: {body_base64}"
        headers["x-digest"] = body_base64

    signature = base64.b64encode(
        hmac.new(secret.encode(), string_to_sign.encode(), hashlib.sha256).digest()
    ).decode()
    headers["x-bigco-hmac-sha256"] = signature
    return headers

A failed signature returns 401 Unauthorized:

{
  "detail": {
    "type": "not_authenticated",
    "msg": "HMAC signature verification failed"
  }
}

Get started

Webhooks

Bulk data

Reference

Authentication

Required headers

Generating the signature

Step by step

Example

​Required headers

​Generating the signature

​Step by step

​Example

Required headers

Generating the signature

Step by step

Example