← BackHome
Cherilin One · Developers

Read your Cherilin account from your own server.

The Cherilin API is small and read-only. Make an API key in your account, send it with each call, and get back the account, its organisations and the products it has.

What works today

Keys

A key looks like chr_ followed by letters and numbers. It is shown once, when you make it. We store only a scrambled form of it, so we can't show it again. If you lose a key, revoke it and make a new one.

Keep keys on a server. Never put a key in a web page, a phone app or a public code repository. Anyone who has the key can read what the key can read.

Make a call

Send the key in the Authorization header.

curl https://account.cherilin.com/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Example reply for a personal key with every scope. The values here are placeholders.

{
  "key": { "id": "k_0123456789abcdef", "name": "Website server",
           "scopes": ["profile:read", "email:read", "orgs:read", "entitlements:read", "usage:read"],
           "owner": "user", "created": "2026-11-22T18:00:00.000Z" },
  "user": { "id": "u_EXAMPLE", "name": "Example Person", "created": "2026-11-01T12:00:00.000Z",
            "roles": ["customer"], "email": "person@example.com", "emailVerified": false },
  "orgs": [ { "id": "o_EXAMPLE", "name": "Example Co", "role": "owner" } ],
  "entitlements": [ { "product": "ai", "plan": "membership", "status": "active",
                      "source": "gumroad", "expires": null, "org": null } ],
  "usage": { "today": 1, "month": 1, "limitPerMinute": 60, "limitPerDay": 10000 }
}

A key made for an organisation returns org in place of user, and the organisation's own entitlements. It never returns details of the person who made it.

Scopes

A scope is one thing a key may read. Choose them when you make the key. Give each key only what it needs.

profile:readAccount id, name and roles.
email:readAccount email address. Emails are not verified yet.
orgs:readOrganisations the account is in, with its role in each.
entitlements:readProducts and plans the account or organisation has, and their status: active, pending, expired or revoked.
usage:readThis key's own call counts and limits.

Limits

Each key may make 60 calls a minute and 10,000 a day. Every reply carries the headers x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset (seconds). When a key goes over, the reply is 429 with a retry-after header. The daily count starts again at midnight UTC.

Errors

Errors are JSON: {"error": {"code": "...", "message": "..."}}.

401 invalid_keyNo key, or a key we don't recognise.
401 revoked_keyThe key was revoked.
404 not_foundNo such endpoint.
405 method_not_allowedThe API is read-only. Use GET.
429 rate_limitedToo many calls this minute.
429 daily_capThe key reached its daily limit.
429 too_many_bad_keysToo many calls with a wrong key from one connection. Wait 15 minutes.

Webhooks

You can save an https address and pick the events you care about: entitlement.updated, order.updated, subscription.updated, invoice.created and org.member.changed. Today this only saves your address. Nothing is sent yet. When sending is switched on, this page will describe the message format and how to check that a message really came from Cherilin.

Payments

Card payments inside Cherilin accounts are not switched on yet. The API does not take payments.

Help

Our contact address is on the privacy page. Never send an API key in a message. Send the key's name or the first characters shown in your account.