Authentication

Integration keys, signing secrets, dry_run and live modes, rotation and what a key may call.

Integration keys#

An integration key belongs to one tenant and one sending system. It has three values, shown once when the key is created or rotated:

VariableUsed forStored by JaKun as
JAKUN_TOKEN=jk_svc_…Authorization: Bearer for REST and MCPSHA-256 hash
JAKUN_KEY_ID=key_…X-JaKun-Key header of inbound eventsplain (it is not a secret)
JAKUN_SIGNING_SECRET=jk_whsec_…HMAC of inbound eventsencrypted

Keys are created by the tenant owner or an admin (permission Configure integrations) in Indstillinger → API. Other members get 403 integrations_admin_only.

Modes#

ModeInbound events
dry_run (default)Processed and rolled back. Status dry_run, result shows what would happen.
liveWritten to the CRM. Status processed.

After switching to live you can apply earlier dry-run events one by one with Process again in the event journal.

What a key can call#

Keys are default-deny. A key reaches only:

  • GET/POST /{object}, GET/PATCH /{object}/{id} — within the key's roles;
  • POST /mcp, GET /mcp/tools;
  • GET /meta/objects, GET /meta/objects/{name};
  • pack-specific endpoints documented in the reference.

Everything else answers 403 service_scope and is written to the audit log. Deleting records, exports, users, keys and webhooks need a person.

Roles#

A key carries tenant roles just like a person. The default for the construction pack is byg_agent. Fields hidden from a role are hidden from the key as well.

Rotate and revoke#

Rotate issues a new token and signing secret for the same key id; the old values stop working immediately. Revoke is permanent: REST and MCP answer 401, inbound events answer 401 bad_key. Both are in the audit log with who and when.

Web session#

The management endpoints (keys, webhooks, event journal, connections) are used by the JaKun web app with the jakun_session cookie of a signed-in owner or admin. They are documented so you know what the screens do; they can't be called with an integration key.