Authentication

Every request carries one of two credentials.

credential	header	who
API token	Authorization: Bearer ias_…	scripts, tools, agents
browser session	the cookie the app sets when you sign in	the app, and your own requests from a signed-in browser

A request without a valid credential is 401 {"error": {"code": "unauthenticated"}}. A credential without the needed permission on the target is 403 {"error": {"code": "forbidden", "details": {"action": "read", "address": "…"}}}.

API tokens

A token is bound to one network and carries a grant: which actions, on which hosts, until when.

Create one in the app (your network, Agents and API tokens, Create token), or from a signed-in browser session:

POST /v1/sessions
{ "name": "nightly report", "scopes": ["search", "read"], "hosts": ["h1a2b3c4d5e6"], "ttlDays": 90 }

{ "id": "ses_7k2m9p4q1r8s3t6u", "token": "ias_n7q2k3m4p5r6s7t8.…" }

The token is shown once. Store it like a password.

field	meaning
name	how the token appears on your network page
scopes	any of search, read, write; see below
hosts	optional; the host ids the token may see. Absent means every host you may see
prefix	optional; an address prefix the token is limited to, such as pad/reports/
ttlDays	optional; default 30

An agent that connects through MCP gets a token of the same kind, minted by the approval page.

Scopes

scope	allows
search	POST /v1/search, GET /v1/get, GET /v1/list, GET /v1/hosts, GET /v1/status
read	GET /v1/o/…: the bytes behind an address
write	PUT and DELETE /v1/o/… on the token’s hosts

Every token may also read and write its own folder on the pad, inseam://{network}/pad/agents/{name}/, whatever its scopes. A token cannot create other tokens, change hosts, or change the plan: those need a signed-in person.

List and revoke

GET /v1/sessions
DELETE /v1/sessions/{id}

GET returns {"sessions": [{id, kind, client, scopes, hosts, created, expires, lastUsed}]} for your own tokens and agents; a network owner sees every member’s. DELETE answers 204 and the token stops working within seconds.

Which network

A token names its network. A browser session covers every network you are a member of: pass X-Inseam-Network: {network id} to pick one. A session with exactly one network needs no header; with several and no header the answer is 400 with the list.

Who am I

GET /v1/me

{ "account": { "id": "acct_…", "email": "you@example.com" },
  "networks": [ { "id": "n7q2k3m4p5r6s7t8", "name": "Home", "role": "owner", "plan": "free" } ] }

Browser session only. A token asks GET /v1/status instead.

Signing in from a script

Sign-in is for people, in a browser: an email link, no password. A script uses an API token. There is no username-and-password endpoint.