Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Cloud API

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    The hosted control API behind Keryn Cloud, at https://api.keryn.app. Version 0.1.0. Pre-1.0: once released, only additive changes inside a minor version. The Usage tag is marked unstable.

    The OpenAPI 3 document is /openapi/keryn-cloud.json. A typed client is on the Keryn SDK page. A test in the monorepo fails when a route is added to the server without being added to the document.

    Credential How to send it Made with
    Organization API key Authorization: Bearer <key> POST /api/v1/keys (Account, Developers)
    Device token x-keryn-worker-token: <token>, never together with Authorization pairing, or POST /api/v1/workers
    Browser session the sign-in cookie, from the Keryn origin only signing in

    A key carries scopes (scans:create, scans:read, scans:cancel, usage:read) and may be limited to projects. Administration (keys, workers, security policy, sharing mode, claiming or redeeming credit) needs a signed-in owner or admin; keys and device tokens are refused there. Privileged calls also need a fresh step-up proof from POST /api/v1/security/step-up.

    • Bodies and answers are JSON. Errors are {"error": "<code>"}, sometimes with a message; internal_error adds a requestId to quote to support.
    • Send x-keryn-organization: <id> to fail with 409 organization_changed if the credential’s organization is not the one you expect.
    • Calls that reserve credits (POST /api/v1/scans) need an Idempotency-Key header, so a retry cannot reserve twice.
    • Every /api/v1 answer to an authenticated caller carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset: the requests a minute that the plan of the organization allows (120 on the free plan, of which 30 may change something), how many are left, and the seconds until the window resets. GET /api/v1/limits returns the same numbers under rate.
    • 429 answers carry retry-after, in seconds.
    • Clients must ignore fields they do not know.
    Method Path Needs What it does
    GET /health nothing Liveness.
    GET /api/health nothing Whether the scan engines loaded. 503 when one did not.
    GET /api/public/config nothing Sign-in providers and whether billing is on.
    POST /api/public/sso-domain nothing Whether the domain of an email address has verified single sign-on.
    GET /api/public/entitlement/keys nothing The entitlement and licence verifying keys, public halves only: the current signing key, earlier ones kept for releases that still pin them, and retired (compromised) ones, whose tokens are revoked.
    Method Path Needs What it does
    GET /s/{token} nothing Read a shared scan result by link. Public; revoked, expired or switched-off links, and links whose maker left the organization (person, revoked key, or a device whose approver left), answer 404.
    GET /api/v1/sharing any credential The organization’s sharing mode, and what it allows per repository visibility.
    POST /api/v1/sharing owner or admin, signed in Set the organization’s sharing mode. Switching to off ends every existing link.
    GET /api/v1/results scans:read Uploaded scan results (100 most recent).
    POST /api/v1/results scans:create Upload a result under the sharing mode. Private source, finding text and evidence are never stored; private repositories keep counts only, and only when the mode is public+metadata. The plan bounds the results an organization keeps (409 result_storage_full) and the report bytes it stores in 24 hours (429 result_upload_limit: 100 MiB on Free).
    GET /api/v1/results/{id} scans:read One uploaded result.
    DELETE /api/v1/results/{id} scans:create Delete an uploaded result and its links.
    POST /api/v1/results/{id}/share scans:create Create a share link for a full public-repo result. 1 to 90 days, default 30.
    DELETE /api/v1/results/{id}/share scans:create Revoke every link of a result.
    GET /api/v1/tracker-claims/{key} findings:triage Shared tracker export claim for one export key (sha256 of destination, scope and canonical case; none of them is stored). Dark until migration 028 and role provisioning.
    POST /api/v1/tracker-claims/{key} findings:triage Claim the first create for an export key across the organization’s devices. acquired is true only for the client allowed to create; otherwise the current claim (creating elsewhere, uncertain, or linked to its ticket) is returned. A retryable claim may be taken over.
    PUT /api/v1/tracker-claims/{key} findings:triage Record the outcome: the owner reports uncertain or retryable; any triager may link an unlinked claim to the ticket found by its marker. A linked claim keeps its ticket.
    GET /api/v1/results/{id}/reviews scans:read Persistent review history across rescans of the same repository. Dark until migration 020 and role provisioning.
    PUT /api/v1/results/{id}/reviews owner or admin, signed in Administrator records an append-only review and current member assignment. Resolution requires comparable successful paired reports; no release approval is issued.
    GET /api/v1/results/{id}/dispositions scans:read Triage decisions on the findings of an uploaded result.
    PUT /api/v1/results/{id}/dispositions findings:triage Record a triage decision on one finding (roles owner, admin, member and triage; never viewer). The audit trail keeps who changed it and the state before and after (the note is not copied there).
    Method Path Needs What it does
    POST /api/pair/start nothing Start pairing a browser, extension, native app or CLI. A signed-in member approves the code.
    POST /api/pair/token nothing Poll for the worker token. 202 while pending, 200 once approved (the token is returned a single time), 410 when expired.
    GET /api/v1/pair signed in What the approver sees for a user code, before approving.
    POST /api/v1/pair/approve signed in Approve a pairing as the signed-in member. The device gets scans:create, scans:read, scans:cancel and usage:read, never administration, for 30 days.
    POST /api/v1/workers/rotate any credential Swap the calling device token (x-keryn-worker-token) for a new one. The presented token stops working at once and the new one never outlives the device’s approval. Keep only the newest token: presenting a rotated-away token revokes the device as a suspected copy. A paired device works only while the member who approved it belongs to the organization.
    POST /api/v1/workers/revoke any credential Sign the calling device out: the device and every token it holds (x-keryn-worker-token) stop working at once. Clients call it when a person signs out, so a copy of the token is useless afterwards. Pair again to sign back in.
    GET /api/v1/devices signed in Devices you paired for this organization (browser, extension, desktop app, CLI), with whether each still works.
    DELETE /api/v1/devices/{id} signed in End a device you paired. Its tokens and entitlements stop at once; a device someone else paired, or a service account, is not found.
    DELETE /api/v1/members/{id}/devices owner or admin, signed in End every device a member paired for this organization, with their tokens and entitlements. The membership stays. Only an owner can do this to an owner.

    Organization and SSO management beyond these calls is served under /api/auth/* by Better Auth and is not part of this contract.

    Method Path Needs What it does
    GET /api/v1/me any credential The calling identity and its active organization.
    GET /api/v1/teams scans:read Teams of the organization with their members. Member addresses and names go only to a signed-in member with organization-wide access; other credentials get member ids.
    GET /api/v1/directory owner or admin, signed in SCIM endpoint and provisioned directory connections.
    POST /api/v1/directory/tokens owner or admin, signed in Create a SCIM directory token (or the first one, which turns self-serve provisioning on). The secret is returned once.
    DELETE /api/v1/directory/tokens/{id} owner or admin, signed in Revoke a SCIM directory token.
    GET /api/v1/account/earlier signed in Earlier keryn.app history under the signed-in person’s verified email: what can be brought (found) or what was brought (linked). Off unless the service enables it (404). People only.
    POST /api/v1/account/earlier signed in Copy the earlier keryn.app scans and domains into the active organization, once per person and per earlier account. Domains arrive unverified. Rows that break today’s limits are skipped and counted. Needs scan rights in the organization.
    GET /api/v1/directory/groups owner or admin, signed in SCIM groups your directory pushed to this organization, with their member count and the team linked to each.
    PUT /api/v1/teams/{id}/projects owner or admin, signed in Replace the projects a team gives its members. A member restricted to some projects reaches the union of their own and their teams’ projects.
    PUT /api/v1/teams/{id}/directory-group owner or admin, signed in Link a team to one SCIM group of this organization: the team’s members become the group’s active members now and follow the directory from then on. null removes the link and keeps the members. Keryn never creates a team from a group.
    Method Path Needs What it does
    GET /api/v1/projects any credential Projects the credential can see (100 at most).
    POST /api/v1/projects owner or admin, signed in Create a project.
    Method Path Needs What it does
    GET /api/v1/keys owner or admin, signed in API keys of the organization (100 at most). Secrets are never returned.
    POST /api/v1/keys owner or admin, signed in Create an organization API key with scopes and an optional project restriction. The key is returned once.
    DELETE /api/v1/keys/{id} owner or admin, signed in Revoke an API key.
    GET /api/v1/workers owner or admin, signed in Worker devices of the organization (100 at most).
    POST /api/v1/workers owner or admin, signed in Create a worker device and its token for a client that cannot hold an API key. The token is returned once.
    DELETE /api/v1/workers/{id} owner or admin, signed in Revoke a worker device and every token it holds.

    Unstable. Credit grants, the starter credit and promo codes landed with this version; the fields of limits, credits and usage events may still change before 1.0.

    Method Path Needs What it does
    GET /api/v1/credits usage:read Credit balance with its grants (starter and promo), the restricted part, and whether the starter credit is still available.
    POST /api/v1/credits/starter owner or admin, signed in Claim the one-time starter credit for the organization. Needs a verified email; limited per address and per hour. A repeat call returns the current credits.
    POST /api/v1/credits/redeem owner or admin, signed in Redeem a promo code for the organization. Every refusal other than rate limiting answers code_invalid, so codes cannot be probed.
    GET /api/v1/usage/cli any credential Local (CLI and editor) usage of the organization for a period: counts per team, member, device, command or day, or with view=events the recorded runs newest first. Organization administrators only. It holds the command, size class, outcome, duration and time of each run and never a path, repository name or finding. Send Accept: text/csv (or format=csv) for CSV; an export is recorded in the audit trail. Offline licences report nothing.
    POST /api/v1/usage/cli scans:read Allow-listed CLI usage records (command, size class, outcome, duration, Deep, minute), attributed to the organization, team, account and device and metered in shadow mode. Local scans are 0 credits. Needs migration 019. Migration 057 makes each optional run ID idempotent per organization and device.
    GET /api/v1/repo-scans/quote usage:read What a hosted analysis of a public repository costs, by size class and stage, before it is run. Hosted repository analysis is not open yet (available is false): this is its published price. A repeat of an unchanged repository costs nothing. Local scanning costs no credits.
    GET /api/v1/usage/statement usage:read What each project, team, member or product consumed in a period, in credits debited from the prepaid balance. The total equals the ledger’s usage debits for the period. Send Accept: text/csv (or format=csv) for the same rows as CSV. A member restricted to projects sees those projects only.
    GET /api/v1/usage usage:read Metered usage events (100 most recent), optionally for one project.
    GET /api/v1/downloads scans:read The newest CLI release members may download, with its files per platform, their sizes and sha256 digests, and the installer. release is null when no release is listed yet. Each url is the members-only download route, never a public link.
    GET /api/v1/downloads/{tag}/{file} scans:read Download a file of a CLI release (members only: the CLI is never published publicly). Redirects to a short-lived signed URL of that asset of the private release; a browser without a session is redirected to sign in.
    POST /api/v1/entitlement scans:read A signed, expiring entitlement token for the calling device (keryn login): organization, team, account, plan, features and limits, with the keys of the requested rule vaults wrapped to the device key. Needs migration 019.
    POST /api/v1/oem/admission owner or admin, signed in Admit the entitlement an OEM partner signed for this organization: the Keryn-signed parent naming the partner and its key, and the child the partner signed for this organization. Keryn checks both signatures and bindings, that the parent is registered and not revoked, and reserves the child’s allocation against the parent’s quotas. The organization’s plan is then the child’s features and limits until the child ends or the parent is revoked. Needs migrations 075 and 084.
    GET /api/v1/entitlements owner or admin, signed in The organization’s entitlements, newest first: device, account, plan, signing key, expiry and revocation.
    POST /api/v1/entitlements/{id}/revoke owner or admin, signed in Revoke an entitlement and the device that holds it; the device signs in again. Online, it stops at its next request; offline, at its token’s expiry plus grace.
    POST /api/v1/entitlements/devices/{id}/release owner or admin, signed in Release a signed-in device from the machine it is bound to, to move it: its tokens for the old machine are revoked and the next machine that refreshes with the device’s credentials becomes its machine. A device is bound to the first machine it presents; any other machine is refused (403 device_machine_mismatch). Needs migration 027.
    GET /api/v1/contract owner or admin, signed in The organization’s active contract (enterprise or government), or null.
    GET /api/v1/licences owner or admin, signed in Offline licence requests and issued licences for the organization’s contract; an issued one carries the file to install with keryn licence install.
    POST /api/v1/licences/requests owner or admin, signed in File one machine’s offline licence request (the JSON keryn licence request writes). Needs a contract that allows offline use; the contract’s device limit caps machines.
    POST /api/v1/licences/{id}/withdraw owner or admin, signed in Withdraw a pending licence request.
    POST /api/v1/usage/agentic-own-key scans:read Record one unbilled own-key model run from an account-paired device. Retries of the same run ID are idempotent per account and organization.
    GET /api/v1/limits usage:read Credit balance, reservations, concurrency and the current price.

    The hosted Keryn MCP server. Tools and examples: https://keryn.dev/docs/reference/mcp-tools/

    Method Path Needs What it does
    POST /mcp nothing to connect; a key or device token for tools/call The Keryn MCP server over streamable HTTP, cloud tools only: one JSON-RPC message or a batch per request, answered as JSON (202 with no body for a notification). initialize, ping and tools/list need no credential; tools/call needs an organization API key or a paired device token, and every tool runs as that credential, in its organization, with its scopes.
    Method Path Needs What it does
    GET /api/v1/ai-attribution/policy owner or admin, signed in Read the organization’s attribution lookback and works-council setting.
    PUT /api/v1/ai-attribution/policy owner or admin, signed in Set the organization’s attribution lookback and works-council setting.
    POST /api/v1/ai-attribution scans:create Attribute AI tool use and AI-assisted commits from commit metadata you post (up to 2,000 commits; never code). The report is returned without storing it. An opted-in webhook may receive only an event and a surface hash. The organization controls lookback and works-council mode. Identity reveals are audited. Per-developer rows need a signed-in organization administrator with a fresh step-up proof. Metered in shadow mode: free when the surface is unchanged.
    Method Path Needs What it does
    GET /api/v1/domains scans:read Domains of the organization with their verification state.
    POST /api/v1/domains scans:create Add a domain to verify (20 at most). Returns the existing record when it is already there.
    DELETE /api/v1/domains scans:create Remove a domain.
    POST /api/v1/domains/verify scans:create Check the proof of control now. Verification lasts 30 days; each attempt counts against an hourly budget.
    POST /api/v1/cloud-scans scans:create Run and store a public-address scan inside the request. Website scans (dast) require websiteTests: true from GET /api/public/config.
    GET /api/v1/cloud-scans scans:read Stored cloud scans, without reports (100 most recent).
    GET /api/v1/cloud-scans/{id} scans:read One stored cloud scan with its report.
    DELETE /api/v1/cloud-scans/{id} scans:create Delete a stored cloud scan.
    GET /api/v1/cloud-scans/usage scans:read This hour’s cloud scans and domain checks of the organization against their limits, and when the hour resets. Also what a Cloud scan costs: trust, surface and MCP scans are free; a website test (kind dast) and active probes are charged from the published per-URL table, held before the scan and refused with 402 when the organization cannot pay.
    Method Path Needs What it does
    POST /api/v1/scans scans:create Queue a trust scan of a public website. Reserves credits for maxPages; pass Idempotency-Key so a retry cannot reserve twice.
    GET /api/v1/scan-schedules scans:read Daily and weekly website scans of the organization (at most 20). A member restricted to projects sees those projects’ schedules.
    POST /api/v1/scan-schedules scans:create Scan a public website every day or week. The first occurrence is due at once; each is admitted as you, like your own scan (credits reserved, limits applied), and a failed one sends failed_scheduled_scan to those who opted in. Missed occurrences are skipped. The schedule stops when you lose the right to scan.
    DELETE /api/v1/scan-schedules/{id} scans:cancel Stop and remove a schedule. Scans it already queued are not canceled.
    GET /api/v1/scans/{id} scans:read Scan status and, once completed, its result.
    POST /api/v1/scans/{id}/cancel scans:cancel Ask a queued or running scan to stop. Unused reservation is released.
    Method Path Needs What it does
    POST /api/v1/billing/checkout owner or admin, signed in Start a credit purchase with the payment provider. Returns the same session for a repeated Idempotency-Key.
    GET /api/v1/billing/settings owner or admin, signed in The organization’s monthly credit cap (null means none), the credits used this calendar month (UTC) and the date the cap resets.
    PATCH /api/v1/billing/settings owner or admin, signed in Set or clear the monthly credit cap. Hosted work that would pass it (a website scan, a hosted AI run, a Cloud scan) is refused before it starts with 429 spend_cap_reached; owners and administrators are told at 50, 80 and 100 percent of the cap and when the balance runs low. Needs migration 052.
    POST /api/v1/billing/portal owner or admin, signed in Open the payment provider’s customer portal.
    GET /api/v1/billing/plans any credential What can be bought, with amounts read from the payment provider: top-up packs (credits equal cents) and the monthly Keryn Team plan. subscription is the organization’s Keryn Team subscription as the payment provider last reported it (null when it never had one; absent before migration 053).
    POST /api/v1/billing/subscribe owner or admin, signed in Start the monthly Keryn Team subscription with the payment provider. Each paid invoice adds the plan’s credits once.
    Method Path Needs What it does
    POST /api/public/telemetry nothing Opt-in product analytics. Each event is rebuilt from an allowlist (enums, counts, durations, a random per-scan run id); anything else is dropped. Nothing about the sender is stored. At most 100 events per call; a global daily ceiling answers 429.
    POST /api/public/diagnostics nothing Send a diagnostic bundle the person previewed (kind keryn.diagnostic). Re-cleaned on arrival, kept 30 days; quote the reference to support. Nothing about the sender is stored.
    Method Path Needs What it does
    POST /api/public/email/subscribe nothing Ask for publications by email (double opt-in). Answers the same for every address; nothing is sent until the address confirms. Marketing topics are chosen later, in the preference centre.
    POST /api/public/email/confirm nothing The double opt-in click: activates the requested publications and returns the address’s preference token.
    POST /api/public/email/preferences nothing Read preferences with the token from any Keryn email.
    PUT /api/public/email/preferences nothing Turn publications and marketing topics on or off. Turning anything on needs the consent wording version; every marketing topic is separate and off by default.
    GET /api/public/email/unsubscribe nothing An unsubscribe link opened in a browser: the email page, which asks before changing anything (link scanners only GET).
    POST /api/public/email/unsubscribe nothing RFC 8058 one-click unsubscribe from one list, one marketing topic or everything (list=all). Needs no session; idempotent.
    POST /api/public/email/export nothing Everything held about the address: lists, consents with their proof, the consent log and deliveries.
    POST /api/public/email/delete nothing Erase the address and everything about it. A keyed hash is kept so it is not mailed again unless it signs up afresh.
    GET /api/v1/email/preferences signed in Your own email preferences, for your verified sign-in address, whichever organization is active.
    PUT /api/v1/email/preferences signed in Change your own email preferences. Your verified address stands in for the confirmation link.
    POST /api/v1/email/export signed in Download what is held about your own address.
    POST /api/v1/email/delete signed in Erase what is held about your own address.
    Method Path Needs What it does
    GET /api/v1/notifications/preferences scans:read Own opt-in notification preferences. Destinations are operator-owned references, never caller URLs or addresses.
    PUT /api/v1/notifications/preferences scans:read Change only your own events and preauthorized Slack/email/webhook destinations. Disabled by default.
    POST /api/v1/notifications/drain owner or admin, signed in Administrator drains one notification with an explicitly configured transport. Without a transport it returns disabled and sends nothing.
    Method Path Needs What it does
    GET /api/v1/audit audit:read The organization’s audit trail, newest first: access, membership, invitations, teams, SSO, MFA, keys, devices, policies, sharing, domains, results, links, dispositions, retention, exports and deletions. Read by a signed-in organization owner or admin, or by an organization API key holding the audit:read scope (not project-restricted; never a worker or device token), so a SIEM can poll it: page with next until it is null, newest first, then keep the newest id seen and poll again.
    POST /api/v1/audit/export owner or admin, signed in The whole audit trail as NDJSON, one AuditEvent per line with type audit_event. The export is itself recorded.
    GET /api/v1/data/retention owner or admin, signed in How long hosted evidence, backups and audit history are kept.
    POST /api/v1/data/retention owner or admin, signed in Set how many days hosted evidence is kept.
    POST /api/v1/data/export owner or admin, signed in Everything Keryn Cloud holds for the organization, as NDJSON (one object per line with a type: organization, member, team, project, sharing_policy, retention_policy, domain, api_key, worker_device, scan_result, disposition, share_link, cloud_scan, scan_job, usage_receipt, credit_ledger, deletion_request, audit_event). Streamed, never stored. Credentials appear as identifiers and dates only.
    GET /api/v1/data/deletions owner or admin, signed in Deletion requests and their completion.
    POST /api/v1/data/deletions owner or admin, signed in Delete all hosted evidence now (uploaded results with their links and dispositions, cloud scans, scan pages and result bodies). Billing receipts, the credit ledger and the audit trail are kept for their own periods. confirm must be the organization id.
    Method Path Needs What it does
    GET /api/v1/security/policy owner or admin, signed in The organization’s MFA, member-scan and SSO enforcement policy.
    POST /api/v1/security/policy owner or admin, signed in Replace the policy. Enforcing SSO needs a verified provider and a session that signed in through it. Turning it on revokes devices people paired before, and invitations are then limited to the provider’s verified domains.
    GET /api/v1/security/session-policy owner or admin, signed in The organization’s session lifetime and idle timeout. They apply to this organization’s requests only.
    PUT /api/v1/security/session-policy owner or admin, signed in Set the session lifetime and idle timeout for this organization. A refused session gets 401 organization_session_expired or organization_session_idle here and keeps working for the person’s other organizations.
    GET /api/v1/sessions signed in The signed-in person’s own sessions (never their tokens).
    DELETE /api/v1/sessions/{id} signed in End one of your own sessions, everywhere.
    DELETE /api/v1/members/{id}/sessions owner or admin, signed in End a member’s sessions for this organization: sessions signed in until now are refused here (401 organization_session_ended); the member’s other organizations are unaffected and signing in again works. Only an owner can end an owner’s sessions.
    GET /api/v1/security/idp-origins owner or admin, signed in Identity-provider origins this organization trusts for its own SSO connections, and whether it has proved a domain by DNS (needed to add one).
    POST /api/v1/security/idp-origins owner or admin, signed in Trust an identity provider’s origin for this organization’s SSO connections, so a connection can be added without a change by Keryn. Needs a domain proved by DNS; the origin must be HTTPS on the default port and resolve only to public addresses. No other organization gains any trust.
    DELETE /api/v1/security/idp-origins owner or admin, signed in Stop trusting an identity provider’s origin. Deleting an SSO connection also removes the origin it used.
    GET /api/v1/security/sso-roles owner or admin, signed in Roles from the identity provider: which groups make a member an admin. null when roles are managed in Keryn only.
    PUT /api/v1/security/sso-roles owner or admin, signed in Set roles from the identity provider. Every SSO sign-in then makes a person an admin when one of their groups is listed and an admin a member when none is (a sign-in without groups counts as none). Owners never change.
    DELETE /api/v1/security/sso-roles owner or admin, signed in Stop setting roles from the identity provider; current roles stay.
    POST /api/v1/security/member-access owner or admin, signed in Allow or deny a member to scan, optionally limited to projects.
    POST /api/v1/security/step-up signed in Prove a fresh MFA code for one privileged request, bound to its hash. Signed-in sessions only.
    Method Path Needs What it does
    GET /api/v1/agentic/price usage:read What each hosted AI feature costs in credits (1 credit is 1 US cent), to show before a run.
    POST /api/v1/agentic scans:create Run an AI feature (summary, threat model, scorecard, exceptions, release, or finding investigation) on a redacted scan brief using Keryn’s model key. The run’s price (GET /api/v1/agentic/price) is held before the model is called and debited when an answer is returned; a refusal, an empty answer or an error is not charged. Finding investigation requires explicit consent and sufficient allowance, then records shadow usage without debiting credits. A daily token cap applies as well.

    Stub. Always refuses until the sandbox runner ships.

    Method Path Needs What it does
    POST /api/v1/builds scans:create Admission check for sandboxed builds. Stub: validates the request and always refuses until the runner ships.

    Sign-in, organizations, SSO and SCIM are served under /api/auth/* by Better Auth. Inbound webhooks from the payment and metering providers are not for clients. POST /demo/mcp is described on the MCP tools page.