Set up device code sign-in

Some devices cannot show a sign-in page: a command line tool on a server, a TV app, a game console. With device code sign-in the device shows a short code such as QSRB-WFXN and a link. The person opens the link on their phone or computer, signs in on your hosted sign-in page, and presses Approve. Meanwhile the device asks BuildBase every few seconds whether it has been approved, and once it has, it receives its tokens. The standard behind it is OAuth 2.0 device authorization (RFC 8628).

Step by step

1. In the BuildBase console, press Users in the left-hand bar (the User management area), then Authentication under Access, and the Settings tab.
2. Press Create auth client.
3. Fill in the dialog:

4. Press Create. The next dialog shows the Client secret once. Copy the client ID and the secret now and keep the secret on your server. If you lose it, open the client's Edit and press Regenerate.

5. Press I've copied the secret, then Edit on the Acme CLI row.
6. Switch on Device code sign-in (RFC 8628). It is off until you do. The address under it is where the device starts, with a POST.

Attach it to your app

The client is the app here. Under Methods in the same sheet, tick the ways people may sign in when they approve a device, then press Update.

Check the preview

The Sign-in page tab's preview shows the sign-in, sign-up and forgot password screens with your look. The device screens use the same card, logo and colours, so a change there shows on them too. To see the device screens themselves, start a real request with the curl command in Try it with curl and open the link it prints.

Your token address

When a person approves, BuildBase sends a signed request to your Application token URL, and your server answers with the token the device will use. The SDK has the whole handler. In a Next.js app:

// app/api/agent/token/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { handleAppTokenRequest, mintAgentToken } from '@buildbase/sdk';

export async function POST(request: NextRequest) {
  const { status, body } = await handleAppTokenRequest({
    authorization: request.headers.get('authorization'),
    clientSecret: process.env.BUILDBASE_CLIENT_SECRET!, // the Acme CLI client's secret
    mintToken: (claims) =>
      mintAgentToken({ claims, secret: process.env.SYSTEM_SECRET! }),
  });
  return NextResponse.json(body, { status });
}

handleAppTokenRequest checks that the request really comes from BuildBase, signed with the client's secret. claims.grantType is device_code, so you can tell a device from a browser sign-in. SYSTEM_SECRET is your app's own signing key (openssl rand -hex 32), which never leaves your server. See MCP and agents.

What people see

The device shows the link and the code (see The code for your device). The person opens the link on their phone or computer:

1. Connect a device. The link fills the code in. They check it matches the one on the device and press Continue. Someone who opens the page without the code types it: 8 letters, and case and the dash do not matter.

2. Sign in to approve Acme CLI. The usual sign-in, with every check it has: a blocked account is refused, and two-step sign-in asks for its code as usual.

3. Approve Acme CLI? The screen lists what the device asked for (openid, profile and email here, in plain words) and warns to approve only a device they are holding. Approve or Deny.

4. You can go back to your device. The device's next check receives the tokens.

The same screens on a phone, where most people approve:

Deny ends the request, and the device is told access_denied:

A code that matches no request, or one that ran out, is refused on the first screen. Five wrong codes from one network address within 10 minutes lock that screen for a while.

An answer is final: once the person approves or denies, a second tab cannot change it. The pages follow the person's language, in any of the 8 languages the sign-in page speaks.

The code for your device

The device makes two calls, both form-encoded, with the client ID and secret:

Show the person user_code and verification_uri, or verification_uri_complete as a link or a QR code. Keep device_code on the device.

Try it with curl

curl -s -X POST "https://api.console.buildbase.app/api/v1/auth/oauth2/device_authorization?org=$BUILDBASE_ORG_ID" \
  -d client_id="$BUILDBASE_CLIENT_ID" \
  -d client_secret="$BUILDBASE_CLIENT_SECRET" \
  -d scope="openid profile email"

Open the verification_uri_complete it returns, approve, then exchange the device_code:

curl -s -X POST "https://api.console.buildbase.app/api/v1/auth/oauth2/token?org=$BUILDBASE_ORG_ID" \
  -d grant_type="urn:ietf:params:oauth:grant-type:device_code" \
  -d device_code="$DEVICE_CODE" \
  -d client_id="$BUILDBASE_CLIENT_ID" \
  -d client_secret="$BUILDBASE_CLIENT_SECRET"

A command line tool

// cli/sign-in.ts
const SERVER = 'https://api.console.buildbase.app';
const ORG_ID = process.env.BUILDBASE_ORG_ID!;
const CLIENT_ID = process.env.BUILDBASE_CLIENT_ID!;
const CLIENT_SECRET = process.env.BUILDBASE_CLIENT_SECRET!;

async function post(path: string, fields: Record<string, string>) {
  const res = await fetch(
    `${SERVER}/api/v1/auth/oauth2/${path}?org=${ORG_ID}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        client_id: CLIENT_ID,
        client_secret: CLIENT_SECRET,
        ...fields,
      }),
    }
  );
  return { ok: res.ok, body: await res.json() };
}

const wait = (seconds: number) =>
  new Promise((resolve) => setTimeout(resolve, seconds * 1000));

export async function signIn() {
  const start = await post('device_authorization', {
    scope: 'openid profile email',
  });
  if (!start.ok) throw new Error(start.body.error_description);

  const {
    device_code,
    user_code,
    verification_uri,
    verification_uri_complete,
  } = start.body;
  console.log(`Open ${verification_uri_complete}`);
  console.log(`or go to ${verification_uri} and enter ${user_code}.`);

  let interval: number = start.body.interval;
  const deadline = Date.now() + start.body.expires_in * 1000;
  while (Date.now() < deadline) {
    await wait(interval);
    const poll = await post('token', {
      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
      device_code,
    });
    if (poll.ok) return poll.body; // access_token, refresh_token, name, email

    if (poll.body.error === 'authorization_pending') continue;
    if (poll.body.error === 'slow_down') {
      interval = poll.body.interval ?? interval + 5;
      continue;
    }
    // access_denied, expired_token or invalid_grant: stop and say why.
    throw new Error(poll.body.error_description ?? poll.body.error);
  }
  throw new Error('The code expired before anyone approved it.');
}

Run against an Acme organization and approved on a phone, it prints:

Open https://auth.acme.example/v1/device?org=6650f1c2a1b2c3d4e5f60718&user_code=QSRB-WFXN
or go to https://auth.acme.example/v1/device?org=6650f1c2a1b2c3d4e5f60718 and enter QSRB-WFXN.
Signed in as Maria Garcia ([email protected]).

The link is your sign-in page's address: your custom domain once you set one on the Domains tab. The secret stays safe only on a device you control. A tool you hand out to customers is better off as a public client, with no secret: register it through dynamic client registration with token_endpoint_auth_method: none and urn:ietf:params:oauth:grant-type:device_code in its grant_types, and leave client_secret out of both calls.

In your app (SDK)

There is no SDK screen for device sign-in: the person approves on your hosted sign-in page, and the device talks to the API directly. The SDK's part is on your server, in handleAppTokenRequest above.

Check it works

• The device_authorization call answers 200 with a user_code. A 400 unauthorized_client means the switch is off.
• The link opens Connect a device with the code filled in, on your sign-in page.
• After Approve, the device's next call answers with an access_token minted by your server.
• After Deny, the device stops with access_denied.

Things to watch out for

• Wait the full interval between checks, the first one too. Start at 5 seconds. Each slow_down adds 5 seconds, and BuildBase keeps the slower pace for the rest of that code.
• A code lasts 10 minutes. After that the device has to start again with a new one.
• The tokens are handed out once. The first check after Approve gets them. A second check with the same device_code is refused.
• A device code can be used for phishing. Someone can start a request on their own device and send a person the link. The approve screen tells people to approve only a device they are holding: say the same in your own help.
• A secret inside a tool you hand out is not secret. Anyone with the tool can read it. Register a public client with no secret instead, as above.
• Your token address has 10 seconds and gets no redirects. BuildBase does not follow a redirect, so an http:// address that redirects to https://, or one that adds a slash, fails with 503 temporarily_unavailable.

If something goes wrong

Next steps

• Device code sign-in - the full reference, scopes and resources.
• Letting agents act for your users - the same OAuth 2.0 server, for AI agents and other apps.
• MCP and agents - the token address in detail.
• Set up sign-in, step by step - every sign-in guide, and the order to set them up in.