s46.apiv1

Quickstart

Authenticate, resolve your team's authorized models, and call the gateway.

Your email must have an active invitation for the target organization/team; otherwise login returns 403 not_invited.

CLI login

brew install sovereign46/tap/s46
s46 login --email you@s46.dev

The CLI handles device login and stores device-bound credentials. Use s46 --help for the commands in your installed release. For a custom client, follow the HTTP flow below.

Start and approve login

curl -X POST https://api.s46.dev/v1/auth/device/start \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@s46.dev","deviceId":"dev-laptop","deviceName":"Dev laptop"}'

The response includes deviceCode, userCode, verificationUri, intervalSeconds, and expiresAt. Open verificationUri and complete browser approval. A GET validates but does not consume a magic-link token; approval requires POST.

Poll for credentials

Poll no faster than the returned intervalSeconds:

curl -X POST https://api.s46.dev/v1/auth/device/poll \
  -H 'Content-Type: application/json' \
  -d '{"deviceCode":"s46_device_..."}'

428 authorization_pending means wait; 200 returns accessToken, refreshToken, and expiresAt plus account/team/device identity. Persist both tokens securely and save the newest rotating refresh token. See Auth for complete login and refresh contracts.

Call the gateway

Use the access token to resolve identity and then the team's authorized models. This example checks HTTP failures before using JSON and refuses an unavailable configured default rather than silently choosing another model:

const accessToken = process.env.S46_ACCESS_TOKEN;
if (!accessToken) throw new Error("Set S46_ACCESS_TOKEN to your access token");

async function request(url, body) {
  const response = await fetch(url, {
    method: body ? "POST" : "GET",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      ...(body ? { "Content-Type": "application/json" } : {}),
    },
    ...(body ? { body: JSON.stringify(body) } : {}),
  });
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
  return response.json();
}

const me = await request("https://api.s46.dev/v1/me");
const team = await request(
  `https://api.s46.dev/v1/teams/${encodeURIComponent(me.team)}`,
);
if (!team.models.includes(team.defaultModel)) {
  throw new Error("Choose an authorized model or ask an admin to update the default");
}
const completion = await request(
  `${team.endpoint.replace(/\/$/, "")}/v1/chat/completions`,
  {
    model: team.defaultModel,
    messages: [{ role: "user", content: "Write a short status update." }],
  },
);
console.log(completion.choices[0].message.content);

Raw HTTP may omit model to request the configured team default; it still must be allowed and servable. For streaming, protocol subsets, output limits, and availability failures, see Gateway. Runtime hints are returned in team metadata; do not hard-code model limits.

On this page