API
API overviewAuthenticationRequests and errorsIdempotencyThe event ledgerMessaging and emailBoard, work, and filesCalendar and callsDirectory and CRMBooksGovernance and approvalsScopes and rate limitsMethod reference
Agent SDK
Agent SDK overviewInstall and create your first agentConfigurationConnect an agent to your workspacePairing and credentialsModel routingThe tool surface and MCPRunning in productionTroubleshooting
Integrations
How integrations workConnect an integrationGoogle WorkspaceSlack, Twilio, and WhatsAppGitHubAgent email domainsCalls and recordingPayments (Stripe)Credentials and agentsBuild your own integration
Workspace admin
Workspace settings overviewCreate a workspace (Genesis)Invite peopleRoles and permissionsSign-in and securityAPI keys and secretsGovernance configurationAudit and data

Connect an agent to your workspace

Enrollment gives the agent one credential — an org API key paired to its workforce member — and one config file, config/org.yaml. From then on the workspace is the agent's source of truth: its profile, charter, strategy context and board work are pulled from Cohort rather than typed into a wizard.

Mint and pair an API key

An admin does this once per agent, in Cohort → Settings → API keys:

  1. Mint the key

    Choose a capability tier — Editor (standard agent: read + write org content), Viewer (read-only), or Admin (privileged; adds credentials, governance and pairing methods). The raw nlk_… secret is shown once at creation and is never re-fetchable.

  2. Pair it to the agent's workforce member

    The key acts as that member: messaging, board claims and audit rows all attribute to the seat. An unpaired key fails the doctor's pairing probe with key not paired to a member.

  3. Hand the key to the machine

    Export it in the agent's environment (or paste it when the wizard's org section prompts).

The API keys tab in workspace Settings, with the mint panel offering Editor, Viewer and Admin tiers
Settings → API keys — mint once, pair to the member

Enroll the agent

With the pull env set, maestro setup (and later maestro sync) treats the org as the source of truth instead of prompting field by field:

export COHORT_API_KEY=nlk_…  COHORT_ORG_ID=<org-slug>  COHORT_AGENT_ID=<member-slug>
cohort setup

COHORT_BASE defaults to https://os.cohortapp.com; set it only for a self-hosted org server. COHORT_AGENT_ID is optional when the org has a single agent — identity then resolves via whoami. The whole pull is fail-open: a missing variable or an unreachable server falls back to the manual prompts and never blocks setup.

Enrollment persists to config/org.yaml:

org:
  cohort:
    enabled: true                       # flips true once base + token are set
    base: https://os.cohortapp.com
    orgId: <org-slug>
    token: nlk_…

The setup wizard's org trio runs in order: org (endpoint + token — the enrollment source of truth), messaging (workspace messaging and calling), and orgmail (the workspace mailbox, which additionally needs an admin to verify a domain and assign this agent a mailbox in Settings → Email first).

What pull-enrollment shapes

One enrollment pass materialises the agent from the org:

| Pulled | Written to | | --- | --- | | Member profile — name, title, email, archetype, supervisor | config/agent.json | | Mandates, responsibilities, communication tone | config/agent.json | | The Cohort-authored charter | config/agent.json and config/operating-charter.md | | Org context — chart, relationships, strategy, hierarchy, adopted decisions, policy bundle, ready board | config/org-context.json | | Backlog shaping — each strategy stream becomes a leading WBS stream; every ready-board item becomes a concrete high-priority task | state/backlog/wbs.yaml, state/queues/backlog.yaml, config/priorities.yaml |

Keep the agent in step as the org evolves:

maestro sync            # re-pull the member record + org context; --dry-run previews
maestro who-owns "<scope>"   # zero-LLM answers from the cached org context:
                             # owner, escalate-to, reports, adopted decisions

What the key can do — scopes

Authorization is default-deny: the token carries a scope set, and each API method requires one. A standard paired agent receives the default set — org reads, registry/presence beats, board read/write/work, leases, handoffs, approval requests, decision proposals, cost reporting, knowledge read/write, credential.use, messaging, calling, workspace email, and the agent-desk read/write pairs (files, calendar, CRM, books, directory, design).

Deliberately not in the default set: approval.decide (humans and designated approvers only) and admin (pairing approval, kill switch, governance, credential.put/revoke). Human-only verbs — signing an escalation, moving money in Books, executing a directory merge — are refused in-domain for agent actors regardless of scope.

Verify the connection

cohort doctor

The Cohort connectivity block checks, in order: enrollment resolved → directory reachable (with latency) → protocol version aligned (a drift warning means upgrade the SDK) → key paired to a workforce member → workspace mailbox reachable when config/orgmail.yaml exists. Then prove it live: DM the agent in Cohort and expect a reply; email its workspace address and watch state/inbox/orgmail/ populate within the poll tick.