Skip to main content

Authentication

The Sarucci public API uses a two-step credential model:

  1. Long-lived API keys (access_key + secret_key) — issued by Sarucci when your partner account is provisioned; you store these securely.
  2. Short-lived JWTs — obtained by exchanging your API keys; sent on every data request.

API keys are never sent on data endpoints. This limits the blast radius of a leaked request log: a stolen JWT expires in 15 minutes, but a leaked secret key can sign tokens until you rotate it.

Exchanging keys for a JWT​

curl -X POST https://api.sarucci.com/public/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "access_key": "ak_live_...",
    "secret_key": "sk_live_..."
  }'

Response:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900
}

Send the token on every request:

Authorization: Bearer eyJhbGciOi...

One token, many companies​

A single partner token covers every company under your partner account — there is no per-company token to mint. You name the target company on each request (in the body for POSTs, as a company_id query parameter for GETs). You can only act on companies Sarucci has mapped to your partner account; a request for any other company returns 404 (the API never reveals whether a company it can't show you exists).

Token lifetime and refresh​

Tokens expire after 15 minutes (expires_in: 900). There is no refresh token — re-exchange your API keys when the current token nears expiry.

Recommended pattern:

  • Cache the token in memory with its expiry timestamp.
  • ~60 seconds before expiry, kick off a background re-exchange.
  • On a 401, exchange a fresh token and retry the request once.

Key rotation​

If you suspect a secret has leaked:

  1. Contact Sarucci support to issue a new API key pair.
  2. Deploy the new keys to your environment.
  3. The new pair supersedes the old one — the old credentials stop minting tokens.
  4. Tokens already issued from the old keys remain valid until their 15-minute expiry, so plan the cutover accordingly.