Overview Authentication API reference Webhooks Errors & limits Deep links Changelog

Authentication

Every request carries a bearer token in the Authorization header. There is no session, no cookie and no unauthenticated endpoint on the API surface — the public share and portfolio pages are ordinary web routes and are not part of this API.

Authorization: Bearer trace_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

Two kinds of token

Device tokens

Minted by the capture app when somebody signs in on a phone. They hold a single narrow ability, capture. A stolen handset can upload photos and read the projects it needs to file them against, and nothing else.

Integration tokens

Created deliberately under Settings → Access tokens, with the scopes you pick and an expiry you choose. This is what your integration uses.

Signing in as a device

POST /api/v1/auth/login

Exchanges an email, a password and a device identifier for a token. Rate limited to 20 attempts a minute per IP.

curl -X POST https://trace.foundrcode.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "…",
    "device_uuid": "9f1c…",
    "device_name": "Site iPhone"
  }'

Scopes

A token carries an explicit list of abilities. Anything not on the list is a 403, not a silent no-op.

Scope	Allows
`projects:read`	Read projects
`projects:write`	Create and update projects
`photos:read`	Read photos and their metadata
`photos:write`	Upload photos and edit captions
`photos:delete`	Delete photos
`checklists:read`	Read checklists
`checklists:write`	Tick checklist items off
`tasks:read`	Read tasks
`tasks:write`	Create, update and close tasks
`pages:read`	Read project pages
`pages:write`	Write project pages
`customers:read`	Read customers
`customers:write`	Create and update customers
`reports:read`	Read reports
`comments:read`	Read comments
`comments:write`	Post comments

Presets

Read only

Read data. Cannot change anything.

Read & write

Read and create data. Cannot delete.

Full access

Read, write and delete.

Custom

Choose exactly which resources and actions to allow.

Expiry and revocation

A token can expire in 30 days, 90 days, a year, or never. Trace stores a hash, not the token, so a lost secret cannot be recovered — only replaced. Revoking one takes effect on the next request; there is no cache to wait out.

A token is a credential for one team. It cannot be widened, and there is no parameter that reads across tenants. If you integrate for several companies on one install, you hold several tokens.