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:

WhatWhere it shows
SlugShort, URL-safe name (acme-ltd-1e7e11)In addresses
NameDisplay 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:

json
{ "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:

text
<slug>.<module>.blesyum.app

If 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:

KindHeaderWhen
API keyAuthorization: Bearer blsk_…Server-to-server automation
SessionAuthorization: Bearer &lt;session-token&gt;The panel's own endpoints
Public—Webhook inbound, widget, health

Details: Authentication.

Licence and access

The licence state decides access directly:

StateAccessMeaning
trialyesTrial running
activeyesSubscription open
pending_payment · pending_reviewno (402)Onboarding incomplete
expired · suspended · canceledno (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.

Bu sayfa işine yaradı mı?