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_.

bash
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.

bash
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 familyWhy open
/healthz · /readyz · /metricsInfrastructure probes
Webhook inboundThe caller doesn't carry our identity; verification is by signature
Live chat widgetThe visitor has no account
/api/v1/i18n/*The sign-in screen must be translated too
/api/v1/timeClock reference — it doesn't even touch the database

401 or 403

This distinction drives your integration's behaviour:

CodeMeaningWhat to do
401No credential, or an invalid oneCheck the key; do not retry
403Credential valid, permission missingCheck the scope or the licence
402Account onboarding incompleteFinish onboarding in the panel
429Rate limitWait 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.

Bu sayfa işine yaradı mı?