Authentication

Every request carries an API key in the Authorization header:

Authorization: Bearer $OPENLATCH_API_KEY

API keys

A personal key belongs to the person who created it, and acts with that person’s current role. An organization key belongs to the organization: it acts as itself, with the admin role, and keeps working when its creator leaves. Every change made with a key records the key as the actor, and the audit trail shows the person through the key for a personal key, and the key’s name for an organization key. Create and manage keys in the console; see Manage API keys.

Role	Can
viewer	Read resources and configuration
editor	Everything a viewer can, plus manage resources and configuration, such as intent policies, zones and agent ownership
admin	Everything an editor can, plus users, teams and settings
owner	Everything an admin can, plus the organization itself

Each operation page names its minimum role. A request without a valid key, or with an expired or revoked one, is refused with UNAUTHORIZED. A request from a role below the operation’s minimum is refused with FORBIDDEN.

Agents

An agent connected to the MCP server signs in with OAuth as the person using it, and acts with that person’s role. Its token works only through the MCP server: sent to the API directly, it is refused. See Use OpenLatch from your agent.

What a key can do

A key reaches an operation only when both its scopes and its role allow it. Each operation page names the scope it needs beside its minimum role, and API key scopes lists every scope.

Key	What it can do
Full access (legacy)	Everything its person’s role allows. Only a key that existed before scopes has full access, and no new one can be created
Scoped personal key	Only the operations of the scopes it holds, within its person’s role. A scope that changes something also grants reading it, and every key can read its own organization and revoke itself
Scoped organization key	Only the operations of the scopes it holds, with the admin role. It is refused every organization-administration operation whatever its scopes, and an operation that describes a person answers it with FORBIDDEN

A scoped key that calls an operation outside its scopes is refused with INSUFFICIENT_SCOPE before its role is checked. The refusal names the missing scope and links to the scopes reference. Create a scoped key as Manage API keys describes.

A leaked full-access key acts with its person’s full role until it is revoked. Reduce that risk: narrow every full-access key, give each integration a key that holds only the scopes it needs, keep keys in a secret store, and revoke a key as soon as nothing uses it.