Identity and access
Authentication
API keys, session tokens and public endpoints — which one when, and how the workspace is resolved.
Blesyum has four separate doors and every endpoint expects exactly one of them. Knocking on the wrong door produces a 401 or a 403 — and those two say different things, so don't conflate them.
API key (PAT)
For server-to-server automation. Created in the panel, prefixed with blsk_.
curl "https://acme.crm.blesyum.app/api/crm/public/v1/contacts" \
-H "Authorization: Bearer blsk_..."Three things to know:
1. The workspace is resolved FROM THE KEY, not the address. This is a security decision: a key only ever sees its own workspace. Even if you send the request to another tenant's host you get your own data back — cross-tenant leakage is architecturally impossible.
2. Scopes open endpoints. If your key lacks contacts.read, the contact list endpoint returns 403. See Scopes.
3. A key has an environment. A key in the test environment does not trigger live side effects: no webhook delivery, no email. You can exercise your integration against real data, quietly.
The secret is shown once and only a digest is stored. Never embed a key in client-side code (browser, mobile app) — a secret kept there is not a secret.
Session token
For the panel's own endpoints. A user signs in, core issues a session token and modules verify it.
curl "https://acme.crm.blesyum.app/api/crm/v1/workspace" \
-H "Authorization: Bearer <session-token>"Using this token in an integration is not recommended: it dies on a sliding timeout (1 day by default, 14 days with "remember me"), it is subject to two-factor challenges, and it is revoked when the user changes their password. Use an API key for automation.
Public endpoints
Some endpoints require no credential, and each has a reason:
| Endpoint family | Why open |
|---|---|
/healthz · /readyz · /metrics | Infrastructure probes |
| Webhook inbound | The caller doesn't carry our identity; verification is by signature |
| Live chat widget | The visitor has no account |
/api/v1/i18n/* | The sign-in screen must be translated too |
/api/v1/time | Clock reference — it doesn't even touch the database |
401 or 403
This distinction drives your integration's behaviour:
| Code | Meaning | What to do |
|---|---|---|
401 | No credential, or an invalid one | Check the key; do not retry |
403 | Credential valid, permission missing | Check the scope or the licence |
402 | Account onboarding incomplete | Finish onboarding in the panel |
429 | Rate limit | Wait out Retry-After |
The hint field in a 403 body is machine-readable and never translated. Branch on it, not on message — that text changes with the reader's language.
Request signing
For high-security integrations a key can optionally be used signed, which prevents an attacker who captured a request from replaying it. See the key's detail screen in the panel.