> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pomerado.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sign in with a code

> Let an agent without a browser get an API key by having a person approve a short code.

An agent with no browser can sign in with a short code that a person approves on any device. The result is an API key for that person's account.

## Sign in an agent

<Steps>
  <Step title="Start a sign-in">
    The agent calls `sign_in` on any Pomerado MCP, or `POST /v1/sign-in`. The answer has `verification_url`, `user_code`, `device_code`, `interval` and `expires_at`.
  </Step>

  <Step title="Approve the code">
    The agent gives the person `verification_url` and `user_code`. The person opens the link, signs in with Google, GitHub or email (or signs up for free, if they have no account), enters the code and approves.
  </Step>

  <Step title="Poll for the key">
    Every `interval` seconds, the agent calls `sign_in` with `device_code`, or `POST /v1/sign-in/poll`. The status stays `pending` until the person approves.
  </Step>

  <Step title="Use the key">
    The poll returns the key's `secret` once. The agent stores it and sends it as `Authorization: Bearer` from then on.
  </Step>
</Steps>

On the REST API:

```bash theme={null}
curl -X POST https://api.pomerado.ai/v1/sign-in

curl -X POST https://api.pomerado.ai/v1/sign-in/poll \
  -H "Content-Type: application/json" \
  -d '{"device_code": "<device_code>"}'
```

## The key it creates

The key carries everything your role allows except managing API keys, billing and the team, so the agent can find, build and run tools, follow its jobs, and use and save your logins. It lasts 30 days. To ask for longer, start the sign-in with `expires_in_days`, from 1 to 90. Revoke it at any time on the Dashboard's **Settings** > **API keys** page.

Approving needs the `api_keys:manage` permission, because approving creates an API key.

<Note>
  Approve only a code you started yourself. Approving gives that agent access to your account.
</Note>

<Accordion title="Details">
  * The code expires after 10 minutes. A denied code answers `access_denied`, and an expired or used one `expired_token`.
  * Polling faster than `interval` returns the status `slow_down` and a longer interval. On REST, a pending poll answers `202` with `Retry-After`.
  * On an MCP's keyless URL, send the new key to the signed-in URL, without `/keyless`.
  * Too many sign-ins started from one network in a day answers `sign_in_limit_reached`. Where device sign-in isn't available, it answers `sign_in_unavailable`: sign in with OAuth or create a key in the Dashboard instead.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.