Quickstart

npm install @one/sdk

1

Create the SDK client

Use the app ID and redirect URL from your ONE app.

app.js

import { ONE } from "@one/sdk";

const one = new ONE({
  appId: "one_test_123",
  redirectUri: `${window.location.origin}/auth/one`,
});

2

Start login

Ask only for what your app needs.

login.js

await one.login({
  age: "18+",
  email: "optional",
});

3

Handle the return

Send the signed proof to your server.

/auth/one.js

const proof = await one.completeLogin();

await fetch("/api/session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ proof }),
});

Configure

appId required

Your public ONE app ID.

redirectUri required

Where ONE returns the user. Add the exact URL to your ONE app.

Request email

Email is not shared by default.

email: false

Do not ask. This is the default.

email: "optional"

The user may share it. Login continues if they decline.

email: "required"

The user must share it to continue.

Required email

await one.login({
  age: "18+",
  email: "required",
});

Login result

The verified server result has one stable shape.

Login

type Login = {
  user: {
    id: string;
    email?: string;
  };
  age?: {
    over18: true;
    verifiedAt: string;
  };
};

Errors

callback.js

try {
  const proof = await one.completeLogin();
} catch (error) {
  if (error.code === "access_denied") {
    // The user stopped login.
  }
}

Show a retry. Do not treat an incomplete check as a failed age check.

Client API

new ONE(options)

Creates a browser client.

one.login(request)

Redirects the user to ONE.

one.completeLogin()

Checks the callback and returns a signed proof.

Server verification

Send the proof to your backend. Verify it before creating a session.

Node.js @one/node Coming later

Python one Coming later

Go one-go Coming later

Server SDKs will verify the signature, issuer, audience, expiry, and age credential. The proof format is open for other languages.