Overview
Authentication, environments, errors and rate limits.
Prefer the SDK. The official
jami-sdkpackage (npm install jami-sdk) wraps every endpoint below with typed results, typed errors, a checkout polling helper, and webhook signature verification — zero dependencies, Node 18+/edge/browser. This reference documents the raw REST surface the SDK talks to.
Base URL:
https://jami.bio/api/jamidevThere is no separate sandbox host — the environment is a property of your organization, and your token determines which one you're operating in.
Authentication
Create tokens in Developer → API Tokens. The plaintext is shown once; only a SHA-256 hash is stored.
Authorization: Bearer jamidev_live_9f2c4e... # production org
Authorization: Bearer jamidev_test_1a7b3d... # sandbox orgTokens are bound to the environment they were created in. If the organization switches
environment, existing tokens return 401 with a message telling you to issue a new one —
a leftover test token can never operate on live data.
POST /checkout is dual-auth: Jami's hosted checkout pages call it anonymously for
any published product, while token callers are scoped to their own organization's products
and unlock extra parameters (like successUrl).
Conventions
- Amounts: integer ETB minor units (santim).
10000= 100.00 ETB. - Bodies: JSON in, JSON out.
- IDs: MongoDB ObjectId strings.
- Errors: appropriate status +
{ "error": "human-readable message" }.
| Status | Meaning |
|---|---|
400 | Validation failed — the message says which field |
401 | Missing, revoked, or environment-mismatched token |
404 | Resource doesn't exist or isn't yours (indistinguishable by design) |
422 | Attempt to change a locked field (pricing model, product type) |
429 | Rate limited |
502 | The payment provider rejected the request |
Rate limits
POST /checkout is limited to 20 requests per 5 minutes per IP. Exceeding it returns
429 — back off and retry after the window.