# auth.md

You are an agent that wants to use AI Inbx on a user's behalf. This file says how to get credentials and how to handle them.

- API: https://api.aiinbx.com/api/v2, with `Authorization: Bearer <credential>`
- MCP server: https://mcp.aiinbx.com/mcp (OAuth; the client signs the user in)
- Console, where the user manages their workspace: https://aiinbx.com/app
- Docs: https://docs.aiinbx.com/llms.txt

## Accounts are created by people

AI Inbx has no agentic registration. A person signs in or creates an account in the browser, and approves what you may reach. You never create an account, and you never see their password.

## Use what is already there

Check these in order and stop at the first that works. Do not ask for a credential you do not need.

1. **MCP.** If you are an MCP client and the AI Inbx server is connected, call its tools. You never handle a key.
2. **CLI.** `aiinbx whoami` exits 0 when a profile is signed in. Every API operation is a command: `aiinbx commands` lists them as JSON.
3. **Environment.** `AI_INBX_API_KEY` in the process environment or the project's env file. Check that it exists by name; do not print it.

## Sign in with the CLI

Install it with `npm install -g @aiinbx/cli` or `curl -fsSL https://aiinbx.com/install.sh | sh`. Then start a device sign-in, which does not wait on a browser:

```bash
aiinbx login --device --non-interactive
# {"verification_uri_complete":"https://aiinbx.com/device?user_code=...","user_code":"...","expires_in":1800}
```

Give the user the link and the code. They sign in, choose the workspaces, and approve. When they say it is done:

```bash
aiinbx login --complete
aiinbx whoami
```

The login is stored in the system keychain. There is no code for the user to read back to you.

## An API key for the app

Code that runs on the user's servers needs a key of its own. Create one with the narrowest scope that works (`read`, `sending` or `full`) and write it straight into the env file, so it is never shown:

```bash
key=$(aiinbx api-keys create --name "<project> local" --scope sending | jq -er .key) \
  && printf 'AI_INBX_API_KEY=%s\n' "$key" >> .env
unset key
```

The key is returned once and cannot be read again. Never ask the user to paste a key into the conversation, never write one into a command, a commit or your output, and make sure the env file is ignored by git. A `401` on a key that used to work means it was deleted: say so and ask the user how to go on.

## Then

Read https://aiinbx.com/SKILL.md. It takes a project from here to its first email sent and its reply answered.