Sign in as a person

Private preview: this is rolling out and may not be available on your account yet.

First-party only today. Personal access tokens are issued to Sumvin’s own apps and approved clients. They are not yet open to third-party apps, so an outside developer can’t complete this flow. To give your own agent access to Sumvin, use the MCP connector or the CLI.

Acting for a person takes one credential: a personal access token. The person approves it in their own browser; your code never sees their password.

Start the browser sign-in

deviceLogin needs an unauthenticated client. It calls onUserCode once, with the address and short code to show the person, then waits for them to approve.

import { createSumvinClient, deviceLogin } from "@sumvin/sdk";

const signInClient = createSumvinClient({ baseUrl: "https://api.sumvin.com" });

const credential = await deviceLogin({
  client: signInClient,
  onUserCode: ({ verificationUri, userCode }) => {
    console.log(`Open ${verificationUri} and enter ${userCode}`);
  },
});

Show the address and code before you do anything else, such as opening a browser, so a person on a remote terminal can still sign in.

Store the token

deviceLogin returns the token and never stores it. Keep credential.token wherever you keep secrets.

Authenticate with it

import { createSumvinClient, sumvinPat } from "@sumvin/sdk";

const client = createSumvinClient({
  baseUrl: "https://api.sumvin.com",
  auth: [sumvinPat(() => readStoredToken())],
});

sumvinPat takes the token, or a function that returns it.In production, personal access tokens only work from approved Sumvin clients, identified by their user-agent. A request that carries the token from any other client, or with no user-agent, is refused with 403 and code CLI-403-001.

Each failure is its own error class, and all of them extend DeviceLoginError.

Error	Means
`DeviceLoginExpiredError`	The sign-in request expired, was declined, or was already used. Start again.
`DeviceLoginNotFoundError`	The API doesn’t recognise this sign-in request.
`DeviceLoginConflictError`	Another process already finished this sign-in.
`DeviceLoginTimeoutError`	Nobody approved it before it expired.

To stop waiting, pass an AbortSignal as signal.

Carrying a Stamped Mandate

An agent that holds a Stamped Mandate token sends it with pintToken. It always travels alongside the personal access token, never instead of it: a request with only a mandate token is refused.

import { createSumvinClient, pintToken, sumvinPat } from "@sumvin/sdk";

const client = createSumvinClient({
  baseUrl: "https://api.sumvin.com",
  auth: [sumvinPat(() => readStoredToken()), pintToken(() => currentMandateToken())],
});

A mandate token only ever narrows what the request may do. It never grants more than the person’s own access.

Start

Act for a person

Check a mandate

Testing

Sign in as a person

Carrying a Stamped Mandate

​When sign-in fails

​Carrying a Stamped Mandate

When sign-in fails

Carrying a Stamped Mandate