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.
Authentication
Section titled “Authentication”| 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.
Conventions
Section titled “Conventions”- Bodies and answers are JSON. Errors are
{"error": "<code>"}, sometimes with amessage;internal_erroradds arequestIdto quote to support. - Send
x-keryn-organization: <id>to fail with 409organization_changedif the credential’s organization is not the one you expect. - Calls that reserve credits (
POST /api/v1/scans) need anIdempotency-Keyheader, so a retry cannot reserve twice. - Every
/api/v1answer to an authenticated caller carriesRateLimit-Limit,RateLimit-RemainingandRateLimit-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/limitsreturns the same numbers underrate. - 429 answers carry
retry-after, in seconds. - Clients must ignore fields they do not know.
Operations
Section titled “Operations”Service
Section titled “Service”| 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. |
Sharing
Section titled “Sharing”| 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). |
Pairing
Section titled “Pairing”| 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. |
Account
Section titled “Account”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. |
Projects
Section titled “Projects”| 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. |
AI attribution
Section titled “AI attribution”| 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. |
Cloud scans
Section titled “Cloud scans”| 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. |
Billing
Section titled “Billing”| 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. |
Diagnostics
Section titled “Diagnostics”| 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. |
Notifications
Section titled “Notifications”| 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. |
Audit and data
Section titled “Audit and data”| 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. |
Security
Section titled “Security”| 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. |
Agentic
Section titled “Agentic”| 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. |
Builds
Section titled “Builds”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. |
Not in this document
Section titled “Not in this document”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.