Keys with hard edges.

Bearer tokens over HTTPS. Scoped by default, separate test and live, and a third kind for agents that can never sign off on money.

API preview · design draftSubject to change

Send your key

Pass the key in the Authorization header on every request. Requests over plain HTTP are refused, not redirected.

Keep keys server-side. Never ship one in a mobile app or browser bundle; use a short-lived token from your backend instead.

osk_test_…

Test keys

Hit a sandbox seeded with the Riverside Medical sample job. Nothing touches your books.

osk_live_…

Live keys

Read and write your real record. Scoped per key, per project if you want.

osk_agent_…

Agent keys

For AI agents and automations. Can read and propose; can never approve, pay, or submit.

Authenticated request

curl https://api.os.construction/v1/projects/prj_24118 \
  -H "Authorization: Bearer osk_test_4eC39HqLyjWDarjtT1zdp7dc"

Scopes

Every key gets the least it needs. A warehouse sync gets read scopes; your ERP bridge gets ap:write. Keys can also be pinned to specific projects.

projects:read
Projects, cost codes, budgets
jobcost:write
Budgets, commitments, cost codes
changes:write
Create and submit change orders
changes:approve
Approve change orders. User keys only.
ap:write
Invoices, coding, lien waivers
billing:write
Pay apps and SOV lines
field:write
RFIs and daily logs
agents:decide
Approve or reject agent actions. User keys only.
webhooks:manage
Create and delete webhook endpoints

Human-approval gate

Agents propose. People approve.

An agent key that tries to approve a change order or its own action gets a 403. The proposal waits in the agent action queue for a person with the right role.

Error · 403

{
  "error": {
    "type": "forbidden",
    "code": "agent_cannot_approve",
    "message": "Agent keys can propose actions but cannot approve them. A user with role project_accountant must approve act_8812.",
    "request_id": "req_3Lw7A"
  }
}

Partner apps planned

If you build a product other contractors install, you'll use OAuth 2.0 with PKCE instead of pasted keys, so each company grants and revokes access on its own terms. Tell us what you're building and we'll design it with you.

Request early access →