API keys and OAuth sessions

Samva has two credential types. They differ in who is acting and how the organization is chosen. This page explains the model; for the exact key formats and error shapes, see the Authentication reference.

Two credentials

An API key carries its organization with it — key-based callers never choose an org. An OAuth session is tied to your user, so it can act on any organization you belong to, and you select the active one.

How device login works

samva login runs the OAuth 2.0 device authorization flow:

1. The CLI requests a device code and shows you a verification URL and a short user code.
2. It opens your browser (or prints the URL with --no-browser).
3. You approve the session in the browser, signed in as your Samva user.
4. The CLI receives a session token and stores it locally (mode 0600).

From then on, requests send Authorization: Bearer <token> instead of an X-API-Key header.

Organization scoping

Because a session is user-scoped, the active organization travels separately as the x-org-slug header:

• In the CLI, set it with samva org use <slug>.
• In the SDK, pass it when you construct an authToken client:

import { createClient } from "samva";

const samva = createClient({
  authToken: process.env.SAMVA_AUTH_TOKEN!,
  headers: { "x-org-slug": "acme" },
});

Session lifetime

Device sessions have no refresh token. A session slides while you use it and expires after a period of inactivity; when it does, run samva login again. There is nothing to rotate or store on a server — that is what API keys are for.

Which to use

• API key — anything unattended: a backend sending email, a cron job, CI. One organization, long-lived, stored as a secret.
• OAuth session — interactive work, especially across multiple organizations, where you don't want a long-lived key on your laptop.

Related