Organizations and keys

An organization owns folders, experiments and API keys, and every request to Metrics acts in exactly one organization. People join as members with a role, by invitation; jobs and agents act through organization API keys (ak_...); a run writes its data with a short-lived experiment token (ik_...). Manage all of it in the app's settings or with the command line after a browser sign-in.

Organizations

Anyone signed in can create an organization and becomes its admin. A person can belong to several and switches between them; the data of one is never visible from another. Folders, experiments and keys cannot move between organizations.

In the app, the organization switcher changes the active organization, and it and the account menu lead to three settings pages:

page	path	what it holds
Organization	`/app/settings/organization`	the organization's profile, members, roles and invitations
Account	`/app/settings/account`	your profile, email addresses and sign-in security
API keys	`/app/settings/api-keys`	create and revoke API keys of the active organization

From the command line:

syvain-metrics org list          # your organizations; current marks the active one
syvain-metrics org switch my-lab # id, slug or name
syvain-metrics org create "My Lab"

Members and roles

Two roles exist by default: admin (org:admin) and member (org:member). Four permissions gate the management routes:

permission	allows
`org:sys_memberships:read`	list members and pending invitations
`org:sys_memberships:manage`	change roles, remove members, invite, revoke invitations
`org:sys_api_keys:read`	list API keys
`org:sys_api_keys:manage`	create and revoke API keys

Admins hold all four. Changing members, invitations and keys therefore needs the admin role. Reading and writing experiment data needs only membership.

syvain-metrics member list
syvain-metrics member role ada@example.com admin
syvain-metrics member remove ada@example.com

Invitations

An invitation emails a link. Following it signs the person in, or creates their account, and joins them to the organization with the invited role.

syvain-metrics invitation create ada@example.com --role member
syvain-metrics invitation list                 # pending only
syvain-metrics invitation revoke orginv_...

Credentials

credential	looks like	acts as	where it comes from	lifetime
organization API key	`ak_...`	the organization	API keys page, `syvain-metrics api-key create`	until revoked or its optional expiry
personal CLI key	`ak_...`	the organization, while you are a member	minted by `syvain-metrics auth login` in a browser	until `auth logout` or revocation
browser sign-in	OAuth tokens in the CLI login	you, in the organization you picked	`syvain-metrics auth login --device`	refreshed by the CLI
experiment token	`ik_...`	one experiment, for writes	`syvain.v2.experiment.open`	24 hours, refreshable
app session	cookie	you, in the active organization	signing in to the app	the session

API keys

An organization API key is what a training job, CI or an agent uses: SYVAIN_METRICS_API_KEY for the collector, the Python API client, DuckDB and the command line, and Authorization: Bearer ak_... for the HTTP API. It reads and writes everything in its organization and belongs to no person, so it keeps working when its creator leaves.

syvain-metrics api-key create ci --description "GitHub Actions" --expires-in-days 90
syvain-metrics api-key list
syvain-metrics api-key revoke ak_...

The secret is shown once, at creation. Servers remember a verified key for up to 60 seconds, so a revoked key can still be accepted for up to a minute. A key cannot manage members, invitations or other keys.

Personal CLI keys

DuckDB and the Python API client read only an API key from the CLI login. So a browser sign-in also mints an organization API key for you on this machine, named syvain-metrics CLI: <your email> on <hostname>, and saves it in the login. Any member may mint one. It acts as the organization, like any key, but the API accepts it only while you are still a member. org switch and org create replace it with a key of the new organization, and auth logout revokes it with the key itself, so logout works without a live sign-in. It appears in api-key list and on the API keys page like any other key; an admin can revoke it there.

Experiment tokens

syvain.v2.experiment.open, sent with an organization key, returns the experiment's id and an experiment token. The token authorizes only /api/v2/experiments/{experimentId}/events of that experiment: lifecycle, metrics, annotations and its own revocation. It expires after 24 hours. syvain.v2.experiment.tokenRefresh, sent with the organization key and the current unexpired token, issues a new one; the old one keeps working for at most 30 seconds. syvain.v2.experiment.tokenRevoke ends it. Each open issues another token without revoking earlier ones. The collector and the Python client's write session do all of this for you; see the HTTP API to do it by hand.

Per-experiment ingestion keys created through the older /api/v1/experiments/{experimentId}/ingestion-keys route are the same kind of credential and still work on the experiment endpoint. New code opens the experiment instead.

Management over HTTP

The CLI's management commands call these routes. They accept only a browser sign-in's bearer token, with the organization in the syvain-org-id header; an API key or an app session cannot manage an organization.

method and path	does
`GET`, `POST /api/v2/user/organizations`	list your organizations; create one
`GET /api/v2/organization/members`	list members
`PATCH`, `DELETE /api/v2/organization/members/{userId}`	change a role; remove a member
`GET`, `POST /api/v2/organization/invitations`	list pending invitations; invite
`DELETE /api/v2/organization/invitations/{invitationId}`	revoke an invitation
`GET`, `POST /api/v2/organization/api-keys`	list keys; create one
`DELETE /api/v2/organization/api-keys/{apiKeyId}`	revoke a key
`POST /api/v2/user/cli-api-keys`	mint a personal CLI key
`DELETE /api/v2/auth/cli-api-key`	revoke the personal CLI key sent as the bearer credential