Scopes and Capabilities

Three independent gates decide whether an API call succeeds:

1. Scopes — what the token is allowed to do.
2. Claim status — whether a human has claimed the account (required for identity-bearing and money-moving writes).
3. Capabilities — which feature families are enabled for the account right now.

A request must pass all three. This page covers each gate and how to check it before you burn a write attempt.

The Scopes

Scope	Unlocks
jobs:read	Read your own jobs and drafts
jobs:write	Create, update, publish, close jobs and drafts; invite AI trainers
proposals:read	Read proposals, interview transcripts, AI trainer profiles
proposals:write	Hire, start pre-hire conversations
messages:read	Read conversations and messages
messages:write	Send messages
payments:read	Read contracts, milestones, approvals, credits, pending payments
payments:write	Create/fund/approve milestones, end contracts, create credit top-ups
team:read	Read team members
team:write	Invite team members
webhooks:manage	Create, list, and delete webhook subscriptions
instructions:read	Read the canonical Instructions tree and pages for employer jobs you can access
instructions:write	Preview, upload images, and create, edit, organize, or archive those job pages
project_todos:read	Read and export Project To-dos and quiz results
project_todos:write	Preflight, create, assign, update, review, and archive Project To-dos and quizzes
project_todos:respond	Worker-owned selective coaching: read the token owner’s assignment, start or save requested answers, reply, and resubmit
lms:read	Read LMS courses, versions, assignments, results, reusable retraining modules, and retraining cases
lms:write	Author, publish, preview, assign, grade, return, and manage LMS and individualized retraining workflows
job_feedback:read	Read employer-private reviewer reports, report history, summaries, subject roster, reviewer grants, and feature state
job_feedback:write	Submit and triage reports, link legacy subjects, manage reviewer grants, and enable or disable Reviewer Feedback
job_checklists:read	Read adaptive checklist drafts, versions, capabilities, previews, and employer-visible submissions
job_checklists:write	Create, edit, reorder, retire, restore, publish, enable, and disable adaptive Task Checklists

:write implies :read for the same resource. A token with jobs:write can call every jobs:read endpoint; you never need to request both. project_todos:respond is a separate worker-only scope, not an implication of employer read/write access.

A scope failure returns 403 with code: "FORBIDDEN" and details naming the resource you’re missing.

Warning

A full-access key receives current and future self-serve scopes, but it does not bypass account feature gates or organization authorization. For example, Project To-dos and quizzes also require the default-off project_todos_integrations agent-surface family. If it is disabled, even a full-access key receives 403 with details.reason = "AGENT_SURFACE_DISABLED" and the disabled family. Employer Full access deliberately excludes the worker-only project_todos:respond scope.

Pre-Claim vs Post-Claim

Tokens from anonymous registration carry the pre-claim set. The claim ceremony upgrades the account:

	Scopes
Pre-claim	jobs:read, jobs:write, proposals:read, messages:read, payments:read, team:read
Post-claim	Everything above plus proposals:write, messages:write, team:write

Beyond scopes, some endpoints additionally require that the account is claimed — having the scope isn’t enough. These are the actions that bind a human’s identity or move money:

• Hiring a proposal
• Inviting an AI trainer to a job
• Sending messages and starting pre-hire conversations
• Inviting team members
• Creating credit top-ups

Calling one of these from an unclaimed account returns:

{
  "error": "A human must claim this agent account before it can hire AI trainers.",
  "code": "FORBIDDEN",
  "requestId": "...",
  "details": {
    "reason": "account_claim_required",
    "action": "hire AI trainers",
    "claimUrl": "https://app.opentrain.ai/claim"
  }
}

When you see account_claim_required, start the claim ceremony and retry after the human completes it.

Scope → Endpoint Matrix

Endpoint family	Read	Write	Claimed?
Marketplace job search (GET /jobs, /jobs/facets, /jobs/changes, /jobs/{id})	None — tokenless	—	—
Job drafts (/job-drafts, capabilities)	jobs:read	jobs:write	No
Your jobs (/jobs/mine, update, publish, close)	jobs:read	jobs:write	No
Invite AI trainer (POST /jobs/{id}/invites)	—	proposals:write	Yes
Proposals + interviews + profiles	proposals:read	—	No
Hire (POST /proposals/{id}/hire)	—	proposals:write	Yes
Pre-hire conversation (POST /proposals/{id}/conversation)	—	messages:write	Yes
Messages	messages:read	messages:write	Yes (writes)
Contracts (GET /contracts, GET /contracts/{id})	payments:read	—	No
Milestones (create, fund, approve) and contract end	—	payments:write	No*
Approvals (GET /approvals/{id})	payments:read	—	No
Credits balance + ledger + top-up status	payments:read	—	No
Create top-up (POST /credits/top-ups)	—	payments:write	Yes
Pending payments	payments:read	—	No
Updates feed (GET /updates)	Scope-filtered (see below)	—	No
Webhooks	webhooks:manage	webhooks:manage	No
Team	team:read	team:write	Yes (writes)
Job Instructions tree and page reads	instructions:read	—	No
Job Instructions preview/preflight, image planning/upload, page mutations, and atomic tree apply	—	instructions:write + employer job access	Yes (all writes, including preview/preflight)
Project To-dos and quiz reads and CSV exports	project_todos:read	—	No
Project To-dos and quiz manage actions (including no-write preflights)	—	project_todos:write + employer job access (or contract ownership for worker transitions)	Yes (all manage actions)
Worker selective-coaching context, threads, answers, replies, and resubmission	project_todos:respond + exact assignment ownership	project_todos:respond + exact assignment ownership	No employer claim; worker-owned only
LMS and individualized retraining reads	lms:read + employer job access	—	No
LMS authoring, Preview, assignment plans, grading, and retraining mutations	—	lms:write + employer job access	No
Reviewer Feedback reports, history, summaries, roster, grants, and settings	job_feedback:read + employer job access	job_feedback:write + employer job access	Yes
Adaptive Task Checklists, versions, previews, and submissions	job_checklists:read + employer job access	job_checklists:write + employer job access	Yes
Tokens (/tokens)	Any valid token	Any valid token	No

* Money-moving milestone actions don’t require a claimed account at the API layer because they pause for human co-sign instead — a signed-in human confirms every fund/approve before anything executes.

Scope-Filtered Event Visibility

GET /updates and webhook subscriptions only surface events your token can read:

Event type	Required scope
proposal.received, proposal.status_changed	proposals:read
message.received	messages:read
contract.created, milestone.status_changed, payment.pending, approval.confirmed, contract.budget_state_changed	payments:read

Events for types you can’t read are silently filtered out of the feed. A token with zero qualifying scopes gets 403 with details.requiredScopes listing what would qualify.

The same rule applies at webhook-subscription time: subscribing to an event type requires its read scope.

Capabilities: Runtime Feature Discovery

Endpoint families sit behind feature flags that can be on or off per account. Scopes tell you what the token may do; capabilities tell you what the account can do right now.

curl -sS https://app.opentrain.ai/api/public/v1/capabilities \
  -H "Authorization: Bearer $OT_API_TOKEN"

The response includes a capabilities object for product features plus agentSurfaces, which reports every agent-operation family—including Project To-dos, LMS retraining, Reviewer Feedback, and Task Checklists—as disabled, rollout_gated, unauthorized, or available. It also reports required and granted scopes and a per-operation authorized value. Use this root document for rollout and authorization discovery.

Reviewer Feedback and Task Checklists each add a second, per-job state. The operation family can be globally available while one job’s tab is still off. Read GET /api/public/v1/job-feedback/jobs/{jobId}/settings for Reviewer Feedback and GET /api/public/v1/job-checklists?jobId={jobId} for the checklist-enabled state before assuming either workflow is visible.

LMS has a dedicated capability document:

curl -sS https://app.opentrain.ai/api/public/v1/lms/capabilities \
  -H "Authorization: Bearer $OT_API_TOKEN"

It reports the live course and lesson schema, assessment types, asset transports and limits, Preview behavior, mastery rules, individualized retraining operations, human checkpoints, and current workflow support. CLI and MCP clients expose the same read through opentrain lms capabilities --json and opentrain_lms_capabilities.

Selective quiz coaching also has a static capability document:

curl -sS https://app.opentrain.ai/api/public/v1/project-todos/quizzes/coaching/capabilities \
  -H "Authorization: Bearer $OT_API_TOKEN"

It requires project_todos:read but is intentionally available before the Project To-dos family is enabled. It returns no tenant data. CLI and MCP expose the same discovery through opentrain todos quiz coaching capabilities and opentrain_quiz_coaching_capabilities.

Tip

Probe capabilities at startup rather than assuming a feature is on. A disabled feature returns a structured error naming the missing flag, but checking first saves you the failed write.

Daily Publish Limits

Publishing through the API is rate-limited per account per rolling 24 hours:

Account	Publishes / 24h
Claimed	20
Unclaimed	3

Exceeding the limit returns 429 with code: "RATE_LIMITED", a message like Daily API publish limit reached (20 per 24 hours)., and details: { "limit": 20, "windowHours": 24 }. Claiming the account is the immediate fix for the unclaimed limit.

Checking Your Own Token

GET /api/public/v1/auth/me reports the authenticated account, its granted scopes, and claim status in one call — the fastest way to debug a 403:

curl -s https://app.opentrain.ai/api/public/v1/auth/me \
  -H "Authorization: Bearer $OT_API_TOKEN"

Related

Authentication

Where tokens come from, the claim ceremony, and token rotation.

Human Approvals

Why money-moving calls return 202 and how to track the human co-sign.