Access and API keys

Your account

Account security is shared across all three products. Open Security in the platform to review sessions, sign out another device, and see whether the account is protected by an authenticator.

You sign in with a code Katara emails you. The code has eight digits, works once and expires after ten minutes. Five wrong tries end a code, and an email address gets at most five codes an hour.

An authenticator app adds a second check at every sign-in. Any app that shows six-digit time-based codes works, such as Google Authenticator, Authy or 1Password. It is optional, and the platform shows Not protected until you set one up. Setup, verification and removal open Katara’s sign-in page.

When you set up your first authenticator, Katara shows ten recovery codes once. Keep them somewhere other than the phone. Each code works once in place of the authenticator. Security shows how many remain, and you can replace the whole set with an authenticator code; the earlier codes then stop working. After five wrong authenticator or recovery codes in fifteen minutes, Katara pauses these checks for fifteen minutes.

If you lose the authenticator and every recovery code, contact Katara support. After support confirms who you are, a reset starts and completes after seven days, with an email each day. Signing in with the authenticator or a recovery code during those days cancels it. When it completes, the account’s authenticators and recovery codes are removed and every session is signed out; sign in with your email and set up a new authenticator.

Katara emails you when an authenticator is added or removed, when a recovery code is used or the codes are replaced, when a reset starts, is cancelled or completes, and when the account signs in from a browser it has not used in the last 90 days. These emails never contain a code or a link that signs you in.

Removing an authenticator needs a sign-in within the last five minutes and its code, and signs the account out everywhere. Removing the last one asks you to confirm. If a removal request is interrupted, sign in again and check the authenticator list before trying again. API keys cannot manage authenticators.

Synapse, Locus and Cortex use Katara’s existing account sign-in. Product requests use a verified Katara application session or a scoped API key. Raw identity-provider tokens are not product API credentials.

Each organization has Test and Live environments. Copy the environment ID from the platform or listEnvironments; never choose an environment by guessing an ID. Every content reference, run, tool version and grant belongs to that organization and environment. Payments from a Test environment settle on the Test network and payments from a Live one on the Live network; Networks names both.

Whether Live work can be paid for belongs to the deployment rather than to either environment. listEnvironments returns live_funding, which is false where the deployment does not take credits; a Live run then has nothing to spend. The portal shows this next to a selected Live environment.

Choose the credential

Use your signed-in platform session for organization administration and human decisions. Server applications use an API key with explicit permissions, expiry and, when needed, a service account or resource restriction. Keep keys on the server; do not bundle them into browser code.

A key can carry permissions for multiple Katara products. You do not need a separate Synapse or Locus key. A key created for Test cannot read or execute resources in Live. Permissions also remain bounded by current membership or service-account authority.

Task	Example key scopes
Discover the current organization	org:read
Inspect definitions and runs	synapse:agents:read, synapse:runs:read
Export recorded run metadata	synapse:runs:read, synapse:runs:export
Publish definitions and start runs	synapse:agents:write, synapse:runs:create
Cancel runs	synapse:runs:cancel
Read or change knowledge	synapse:memory:read, synapse:memory:write
Allow a managed run to index an existing collection	synapse:memory:read, synapse:memory:index, plus the run’s other permissions
Allow a managed run to describe images in a collection	synapse:memory:read on the collection and its sources, cortex:inference and locus:actions:execute, plus the run’s other permissions
Discover or publish tools	locus:tools:read, locus:tools:write
Read or issue grants	locus:grants:read, locus:grants:write
Read or publish policies	locus:policies:read, locus:policies:write
Use inference in a managed run	cortex:inference, synapse:runs:create, plus the run’s other workload permissions
Call inference directly	cortex:inference with an explicit direct payment mode

These are examples, not permission bundles. Additional permissions can be required by the action you perform. A scope name appearing in the key schema does not establish that every related product feature has shipped.

Index publication also requires current writer access to the selected collection. Its funded grant must include the indexing permission and the collection resource. It cannot create content, change collection membership or approve a memory version.

Choose Managed runs only for a key that starts funded agent runs. Include cortex:inference and synapse:runs:create, and omit the direct billing mode. This works in Test or Live and supports service accounts and resource restrictions. The run still needs current grants, payer consent and a funded budget.

Choose Direct Cortex and managed runs when the key also calls the inference API directly. Direct access requires an explicit payment mode, a personal key and no resource restriction. In a Test environment the payment mode is your wallet, in test USDC: Account Credits do not pay for direct Test calls. A managed-only key cannot call direct inference, even though it carries cortex:inference.

For server identity creation, role changes and disabling access, see Service accounts.

Human review stays with a person

An API key cannot make an action-approval decision or activate a policy. The reviewer uses a verified application session. Current team membership, reviewer eligibility and policy quorum are checked when the decision is made.

Creating a key does not grant spending consent, approve content, activate a tool or override a policy. Keys are shown once at creation, in a dialog that stays open until you confirm you saved the key. A retried create operation can return the key’s metadata without returning the secret again. Revoke a key whose secret was lost and create a replacement.

A key stops working at its expiry, and so does every integration that uses it. When 80% of its lifetime has passed, its holder gets an organization.key_expiring reminder linking to the key under API Keys. Create the replacement with the same name in the same environment; a newer key with the same name that lasts longer counts as the replacement, and no reminder is sent for the old one after that.

Requests and retries

Product routes start at /katara/v1, using the API origin rather than the OpenAI-compatible /v1 base URL. The SDK adds the route prefix.

Most mutations that accept an idempotency key take 8–128 letters, digits, dots, underscores, colons or hyphens. Some take a lowercase UUID instead, and their reference entries say which. Keep the same key and request body when recovering from a lost response. A new key can mean a new operation. The clients do not automatically retry uncertain mutations.

Cookie-authenticated mutations require the current signed-in browser, an allowed origin, X-Katara-CSRF: 1 and X-Katara-Account-ID with the UUID of the account that loaded the application. Set cookieSession: true and expectedAccountID on the TypeScript client. It includes cookies and sends both headers; subsequent reads also carry the account ID.

If another tab signs in as a different account, the API returns 409 account_changed before changing product state. Reload and review the action with that account. A fresh session for the same account can recover the original operation with its unchanged request and idempotency key. Native session bearer and API key requests are bound to their credentials and do not require the account header.

Read the returned error’s code and request_id. A 403 can mean current authority no longer permits the operation. A 409 can mean a revision or approval changed; fetch the current record before deciding what to do next.

Manage organization access

Organization administrators can invite a person, change a member’s role, manage teams and transfer ownership. An invitation names either an email address or the user ID of an existing account, never both. Katara emails the link to an address and says whether it did in email_sent; an invitation by user ID raises a notice in that account instead. The reply that creates an invitation also carries its one-time token, so the link can be shared by hand if the email does not arrive. A repeated request returns the original operation without the token and sends nothing; revoke the invitation and create another if the token was lost. An address can hold one open invitation to an organization at a time (invitation_open), and an organization can create 100 invitations in 24 hours (invitation_limit_reached).

TypeScript sends either recipient through invite. Python has invite for a user ID and invite_by_email for an address.

The recipient signs in and opens the invitation. An email invitation opens only for the signed-in account whose confirmed email address matches it; any other account is refused with invitation_address_mismatch. Review the organization name, role, inviter ID and expiry before accepting. reviewInvitation / review_invitation takes the token in a JSON request body and returns the exact review digest and version. Pass that token, expected_digest and expected_version to acceptInvitation / accept_invitation. These operations require an account session. A changed organization or invitation requires a new review; acceptance never switches to another account or role silently.

If acceptance returns no response, recover with the identical reviewed body and original idempotency key. Do not request a new review for an already accepted invitation. Recovery still requires the intended account and an active membership. The token stays out of query parameters, notification records and persistent client storage.

listInvitations / list_invitations returns each recipient’s email address or user ID, roles, expiry and accepted or revoked timestamps; an accepted email invitation also names the account that accepted it. It never returns invitation secrets. revokeInvitation / revoke_invitation prevents acceptance of an unaccepted invitation; it does not remove an existing member. Change the existing membership to remove access. Keep the same request key when retrying an uncertain revocation.

Use listTeamMembers / list_team_members to inspect a team’s current roster. Team membership and organization membership are separate: removing someone from a team leaves their organization role intact. Role changes require the current member version; ownership transfer requires the current organization version. Reload after a conflict before approving a new change.

Reset a Test environment

An organization owner can reset the selected Test environment from Locus → Environment. Review its organization, environment ID and current generation, then type the displayed confirmation exactly. Only a person signed in to the portal can reset an environment; an API key cannot. Live environments cannot be reset.

Reset fences work admitted under the old generation and retires its Test authority, connections and derived data. Real charges, audit records and reconciliation evidence remain. Customer-object cleanup runs asynchronously. A completed reset receipt proves the generation changed; it does not confirm that physical deletion finished.

SDK callers use getEnvironment / get_environment to read the scoped environment, then resetEnvironment / reset_environment with expected_authority_epoch and expected_reset_generation from that exact review. Use a verified human session and supply a new idempotency key for that reset intent. An API key cannot reset Test.

After a lost or uncertain reply, keep the exact body and key and explicitly recover with them. The same reset key remains valid after its generation change and returns the original receipt without resetting again. Do not replace it with a fresh key to resolve uncertainty. The portal keeps the reviewed request fixed while Recover Reset Result is available. It saves recovery metadata for the signed-in account and environment before sending. Reloading the same browser tab restores that request; type the confirmation again to recover it. Recovery never runs automatically. Keep the tab open until the result is known, since closing it clears this recovery metadata.

The receipt identifies the generations and authority epoch for that reset. A later reset may already have advanced the environment again. Reload the workspace after a confirmed reset before creating new Test work. A stale review must be inspected again; changing the request creates a different reset intent.

Recorded administration operations

Open Locus → Audit to inspect completed administration operations for the selected organization and Test or Live environment. Owners, admins, operators and reviewers need current locus:audit:read authority. API keys must carry that scope; a key with resource restrictions sees only records for its exact allowed resource IDs.

Each record identifies the operation, actor, resource, original reset generation and creation time. The directory covers supported recorded changes to authority, budgets, agents, tools, content, collections, evaluation material, runs and Test resets. Supported records also include controlled rollback reviews and activations, and credential connections, reconnections and revocations. OAuth records cover completed authorization setup and account activation metadata; they omit authorization URLs, state, codes and provider tokens. These entries identify the completed operation without returning credential material.

Repository records cover attaching, renewing and detaching a repository and asking for a sync. Linking and unlinking the GitHub App installation are the organization’s, and a member linking or unlinking their GitHub login is their own; both appear in every environment with its current reset generation. Each document version Katara approves while reading a repository is listed as repositories.versions.approve, with the person whose attaching or renewing gave the approval it acted under as the actor. The directory does not contain every execution event, denied request or organization-wide change.

Use Next Audit Page and Previous Audit Page to inspect bounded pages. Refresh starts with the newest records. Historical records remain visible after a Test reset; the page’s current generation can differ from a record’s original generation. Reading those records still requires current authority.

SDK callers use listAuditOperations(scope, after?, limit?) or list_audit_operations(org_id, environment_id, after=None, limit=25). The REST route is GET /katara/v1/orgs/{org_id}/environments/{environment_id}/audit. The page size is 1–25, defaulting to 25. Pass the returned next_cursor unchanged for the next page. Cursors expire after 15 minutes and are bound to the account, credential, environment and current authority. Refresh after a reset, authority change or expired cursor. Responses contain metadata only, without content bodies or credential material.

Seal the directory for handing over

Export Audit Directory on the Audit page, or createAuditExport / create_audit_export, seals the directory as it stands into a snapshot that can be read back until it expires, from one minute to one day after sealing. It takes the same authority as reading the directory, held by a person rather than a workload. A key with resource restrictions seals only what it may already read. A directory of more than 10,000 operations is refused rather than cut short. Sealing is itself a recorded operation; keep the original idempotency key after an uncertain response.

getAuditExport / get_audit_export reads the manifest and readAuditExport / read_audit_export its rows in sealed order. Each row carries the digest it was sealed with, and the manifest digest covers every row digest in order; verifyAuditExport in TypeScript checks a complete copy. A row that no longer matches its seal is refused rather than served.

Review who holds access

Locus → Access Reviews freezes who holds what in the environment: organization members, service accounts, team seats, keys and grants. One review is open at a time. An owner or administrator, signed in as a person, answers each entry once, keep or remove. Recording remove does not remove anything: remove the access yourself, then close the review. It refuses to close while an entry is unanswered or an entry marked for removal still holds access.

Operation	TypeScript	Python
Open a review	openAccessReview	open_access_review
List reviews, open and closed	listAccessReviews	list_access_reviews
Read a review and its entries	accessReview, accessReviewItems	access_review, access_review_items
Answer one entry	decideAccessReview	decide_access_review
See removals still pending	accessReviewOutstanding	access_review_outstanding
Close the review	closeAccessReview	close_access_review
Record how often to review	setAccessReviewPolicy, accessReviewPolicy	set_access_review_policy, access_review_policy

Every operation needs locus:audit:read. Opening, answering, closing and recording the cadence refuse API keys and take a UUID as the idempotency key; reads accept a key with that scope.