# Connect to Pixelbase, for agents

Pixelbase runs a business's operations — customers, invoices, payments,
scheduling, staff, the ledger — behind one API. If you are an AI agent asked to
connect to your person's Pixelbase — whether they are new to it or already have
a company there — this is how.

Every way in ends with the person you work for approving you in their own
browser, choosing which companies you may reach and what you may do in each.
You cannot approve yourself, and you never handle their card or their
verification code.

## 1. Connect over MCP — start here, new or existing account

Add `https://www.pxb.app/mcp` to your MCP client and authenticate. This is the way in
for everyone: you do not need to know whether your person has an account.

Authenticating opens https://www.pxb.app/oauth/connect in the person's own
browser. That one page covers every case:

- **New to Pixelbase**: they sign up there — their company, mobile number, a
  card (free trial, nothing charged today) and a code texted to their phone.
- **Has an account**: they sign in, or continue as the account already signed
  in on that browser.
- **Locked account** (a PIN): they unlock it. "Use a different account" starts
  over with another one.

**Do not ask the person for their company name, phone number, name or card.**
The page collects all of it, and you never see their card or their code. When
they finish they approve you, choosing which companies you may reach and what
you may do in each. Then call `whoami`: it names the companies you reach and
the tools each one unlocks.

## 2. No MCP, or no browser where you run: device sign-in

Register a device-only client once (skip this if you already have a
`client_id` that declares the device_code grant), then ask for a code:

```bash
curl -X POST https://www.pxb.app/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "<your name, shown to them>",
        "grant_types": ["urn:ietf:params:oauth:grant-type:device_code"],
        "token_endpoint_auth_method": "none" }'

curl -X POST https://www.pxb.app/api/oauth/device-authorization \
  -d client_id=<client_id>
```

Show the person `verification_uri_complete` (or `verification_uri` and the
`user_code`); they open it on any device and get the same connect page as
above, new account or not. Then poll
for your tokens:

```bash
curl -X POST https://www.pxb.app/api/public/v1/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d client_id=<client_id> -d device_code=<device_code>
```

`authorization_pending` means keep waiting; poll every `interval` seconds
(`slow_down` adds five). `access_denied` means they declined;
`expired_token` means start again. Success returns an `access_token` (one
hour) and a `refresh_token` — use them below.

## 3. Other ways in

- **Shell**: `curl -fsSL https://www.pxb.app/cli/install.sh | sh`, then `pxb auth`
  (`pxb auth --device` with no local browser).
- **Unattended, one company**: a company API client from https://www.pxb.app/dev/api,
  exchanged with `grant_type=client_credentials`. It needs an existing
  account, since someone has to create the client.

## 4. Working in the company

Send the token as `Authorization: Bearer <token>`. With several companies,
say which with `X-Company-Id` (REST) or `companyId` (MCP tools).

Over MCP, `list_*` and `get_api_resource` read; the other tools change data
as the person, and only those they granted appear. Confirm with them before
anything that deletes, voids, archives or cancels, and before emailing a
customer. Moving money, buying domains, hiring agents and inviting people stay
in the console.

## Reference

- API: https://www.pxb.app/docs/api/docs.md
- MCP: https://www.pxb.app/docs/mcp/docs.md
- CLI: https://www.pxb.app/docs/cli/docs.md
- OAuth discovery: https://www.pxb.app/.well-known/oauth-authorization-server