Getting started
Concepts
Workspace, module, slug, tenant address and licence — five ideas to know before the API makes sense.
Blesyum is a multi-tenant platform, and that shapes the API directly: every request must belong to a workspace, and that belonging is never guessed — it is proven.
Workspace
The unit that billing, your team, module subscriptions and all data hang off. A person can be a member of several workspaces with a different role in each.
A workspace has two identities:
| What | Where it shows | |
|---|---|---|
| Slug | Short, URL-safe name (acme-ltd-1e7e11) | In addresses |
| Name | Display title (Acme Ltd.) | In the panel, on invoices |
The slug is an address and is produced by folding non-ASCII letters down (Ölçüm Şirketi → olcum-sirketi). Don't construct it in code; read it from the panel or from the /api/v1/me response.
Module
ERP, CRM, Commerce, B2B, Call Center, Mail, Advisor and Ads are modules. Each is a separate service with its own endpoint family and database schema — but they share the identity, error and pagination contracts.
To call a module's API your workspace must be licensed for it. Without a licence the endpoint returns 403 and says why:
{ "error": { "code": "CRM-LIC-0001", "message": "This module is not in your subscription.",
"hint": "module_not_licensed" } }The hint field is machine-readable and never translated — branch on it, not on message.
Tenant address
Every module has its own address for every workspace, and it comes into existence on its own; you never have to ask for it:
<slug>.<module>.blesyum.appIf you connect your own domain (erp.yourcompany.com), that becomes the module's address. The platform address keeps working, but browser requests are redirected to yours.
Never hard-code an address, in the panel or in your code. The correct source is the url field of GET /api/v1/modules: it changes by itself the day a customer connects their own domain.
Identity: who is calling
There are three kinds of caller, and every endpoint expects one of them:
| Kind | Header | When |
|---|---|---|
| API key | Authorization: Bearer blsk_… | Server-to-server automation |
| Session | Authorization: Bearer <session-token> | The panel's own endpoints |
| Public | — | Webhook inbound, widget, health |
Details: Authentication.
Licence and access
The licence state decides access directly:
| State | Access | Meaning |
|---|---|---|
trial | yes | Trial running |
active | yes | Subscription open |
pending_payment · pending_review | no (402) | Onboarding incomplete |
expired · suspended · canceled | no (403) | Subscription closed |
On a closed subscription every module returns the same 403 with the same hint, whichever one you call. That is deliberate: so your integration can decide in a single branch.