Get started

Authentication

Bearer tokens, the three kinds of key, and what each one may do.

Every request except the public ones carries a Bearer token:

http

GET /user/me HTTP/1.1
Host: api.sevennadi.si
Authorization: Bearer vk-0123456789abcdef0123456789abcdef

Kinds of token

Prefix	Kind	Created by	Lifetime	Acts as
`vk-`	API key	`POST /auth/api-keys` or the dashboard's Developers page	Until revoked	admin
`sa-`	Sub-account key	`POST /sub-accounts/create`	Until the sub-account is deleted	admin of the sub-account
`vs-`	Session token	`POST /auth/login`	7 days	the member's own role

Each is the prefix followed by 32 hexadecimal characters. A token is shown once, when it is created. The platform stores only its SHA-256 hash, so a lost key cannot be recovered: revoke it and create another.

Roles

Roles are enforced on every authenticated request from one table on the server.

Role	May
viewer	Read.
member	Also change agents, knowledge bases, batches and campaigns, and place calls.
admin	Also manage phone numbers, SIP trunks, provider keys, custom models, API keys, compliance settings, the do-not-call list, account settings, sub-accounts, the team and the security log.
owner	Also transfer ownership, close the workspace, top up the wallet and change the plan.

API keys act as admin. That means a key cannot do the owner-only actions: topping up and changing the plan need a logged-in owner. GET /auth/me returns the caller's role and the rule table. The reference pages state the minimum role of each operation.

Email verification

If the deployment sets REQUIRE_VERIFIED_EMAIL, outbound calls, batches, campaign starts, workflow runs and API-key creation answer 403 until the login's email address is confirmed:

json

{"error": 403, "message": "Verify your email address first (Settings → Security, or the link we emailed you)."}

Failures

Status	Message	Meaning
401	`Access denied`	No token, a malformed header, an unknown or revoked key, a disabled member.
401	`Session expired`	A session token older than 7 days. Log in again.
403	varies	The token is valid but the role may not do this.

Public endpoints

These need no token: GET /health, GET /ready, the website lead forms under /public/, and the callbacks that payment and messaging providers call (which are checked by signature instead). See Operations and Leads.

Keeping keys safe

Use a separate key per integration, named for it, so one can be revoked alone.
Keep keys on your server. Never ship one in a web page or a mobile app.
Key creation and revocation are written to the workspace's security log (GET /team/audit).