# Authentication and authorization

| Principal | Credential | Authority |
|---|---|---|
| Human | `ordan_session` cookie | Org membership/role; explicit owner approvals |
| Project integration | `Bearer ordan_sk_live_…` | Owner-minted project key scopes; constrained project |
| Agent runtime | `Bearer ordan_sk_agent_…` | Active credential + grant + pinned policy + Line binding |

Never transmit credentials in URL query parameters, prompts, or logs. API
keys and agent secrets are shown once when issued; rotation or revocation
invalidates authority. An anonymous device request creates no permission
until the human approves it.

## Human setup

1. `POST /v1/auth/signup {email,name,password}` (10–200 character password).
2. Verify the emailed token via `/v1/auth/verify-email`; then log in.
3. Create the organization (`POST /v1/orgs {name}`) — it comes with a
   default project and policy.
4. Use owner/admin approval for grants and device pairing requests. A
   developer can mint scoped project keys; `grants:write` expressly
   authorizes delegation.

Roles are `OWNER`, `ADMIN`, `DEVELOPER`, `BILLING`, `VIEWER`. Grant
creation/revocation and Line binding are ADMIN/OWNER decisions. Membership
is managed senior-to-junior, never against the owner: an organization keeps
the owner who created it, nobody changes their own role, and role changes
or removals are audited.

## Agent capabilities

`voice.outbound`, `voice.inbound`, `sms.send`, `sms.receive`,
`numbers.provision`, `numbers.release`, `calls.transfer`, `calls.hangup`,
`calls.record`, `calls.dtmf`, `purchases`, `policy.check`, `usage.read`,
`events.read`.

A valid token alone does not authorize an action: the grant must be live,
include the capability, bind the Line, satisfy policy/time/destination
rules, and fit its cost budgets. Grants pin immutable policy versions —
editing a policy creates a new version and never silently relaxes an
existing grant.

Project key scopes include `agents:read/write`, `grants:read/write`,
`lines:read/write`, `calls:read/write`, `messages:read/write`,
`usage:read`, `events:read`, `webhooks:read/write`, `purchases:read/write`
and `device:authorize`. Keys cannot reach another project; an agent reads
only its own communications and activity. The running OpenAPI contract
exposes the exact registry.

## What agents cannot do

Agents cannot mint owner keys, approve their own grants or approval
requests, claim a business's messaging registration authority, or sign a
porting letter of authorization. They may prepare a request and ask the
authorized human. Revoking a grant, Line, or capability ends that authority
immediately and triggers carrier hangup/stop recovery.