Why Ground Control helps agents · Full Agent Onramp and API contract
Set up with gctl
Before you create anything, ask your user whether they already have a Ground Control account, and stop until they answer; do not assume they have none. If they do, connect to it in step 2, and do not create a workspace for them.
gctl is Ground Control's command-line client for Linux and macOS (amd64 and arm64), and the recommended client for an agent with a shell. It is published only at dl.groundcontrol.so. A package named gctl on PyPI, npm or another package registry is not Ground Control.
1. Install the current release, gctl-v0.27.0, with the three commands below. Run each one as its own command, in the directory where ./gctl will live; they need no temporary directory, and nothing needs removing afterwards. They run no script they download. First find the asset for this machine in the table, from uname -s and uname -m, and write it in place of <asset> in each command.
uname -s | uname -m | <asset> |
|---|---|---|
Linux | x86_64 | gctl_ |
Linux | aarch64 | gctl_ |
Darwin | x86_64 | gctl_ |
Darwin | arm64 | gctl_ |
Before you run them, tell your user in one line what they fetch: the gctl binary for this machine and the release's SHA256SUMS, both from dl.groundcontrol.so. If your user or your environment blocks a command, stop and ask your user to approve it or to run the three commands themselves. Do not switch to the HTTP API to get around a blocked install.
Download the asset from https://dl.groundcontrol.so/gctl/gctl-v0.27.0/.
curl -q -fsSL --proto =https -o '<asset>' 'https://dl.groundcontrol.so/gctl/gctl-v0.27.0/<asset>'Check it against its line of the release's SHA256SUMS. On macOS, write shasum -a 256 -c in place of sha256sum -c. If the check fails, it exits 1; then do not run the next command, and ./gctl stays as it was.
curl -q -fsSL --proto =https https://dl.groundcontrol.so/gctl/gctl-v0.27.0/SHA256SUMS | grep -x "[0-9a-f]\{64\} <asset>" | sha256sum -cWhen the check printed <asset>: OK, write the asset as ./gctl in the current directory and make it executable.
mv '<asset>' gctl && chmod +x gctlA person can install the same release with the release's installer instead. The gctl README prints it as one command.
sh -c 'script=$(curl -q -fsSL --proto =https "https://dl.groundcontrol.so/gctl/gctl-v0.27.0/install.sh") || exit; case $script in "#!/bin/sh"*) printf "%s\n" "$script" | GCTL_INSTALL_SOURCE=public sh ;; *) printf "%s\n" "gctl install: result=install_fetch_failed reason=the response is not the install script, so nothing was run remediation=check that the URL names a gctl-v tag, then rerun the install command" >&2; exit 1 ;; esac'2. Connect to your user's account. When your user asks how they can connect you, first name the three ways in Ways to connect below and what each costs: gctl, one file to install, with no restart and only the output of its commands in your context; the HTTP API, nothing to install, but you build each request from its operation's description; and MCP, a connector your user adds and approves in a browser, often a client restart, and tool descriptions in your context on every turn. The sign-in routes below are how gctl connects. If your user has an account, give them one step, and stop until they have done it: in their own terminal on this machine, as the same computer user you run as, they run this command, sign in on the page it opens in their browser, and click "Approve and connect".
./gctl --host <host> loginIf no browser opens, gctl prints what to do instead. gctl then holds a session for your user, which your own gctl commands on this machine use. The session lasts 365 days, and gctl renews it on its own while it is in use: for a session signed in or renewed by gctl v0.11.0 or later, the first gctl command after the session is halfway through its life renews it for another 365 days, so a session that a gctl command uses at least once every 182 days does not end. A session signed in with an earlier gctl renews only in the last minute before it ends, until its first renewal; your user runs ./gctl --host <host> login once after upgrading to start this schedule. A session left unused for longer can end; gctl then stops with re-authenticate with gctl login, and your user runs ./gctl --host <host> login again. That session is enough to do governed work, so a separate agent key is optional; you can add one later. Governed commands then use the workspace that session signed in to, so they need no --tenant; ./gctl --host <host> status prints its workspace ID as oauth_tenant_id. Some gctl commands refuse a signed-in session and need an API key. Never ask your user for their password.
If you start the sign-in yourself, do not run gctl login or gctl login --manual. The browser sign-in needs its command to keep running until your user approves, and --manual needs a person to paste into its terminal. Run this command instead. It prints a link (verification_uri_complete) and a code (user_code), keeps the sign-in, and returns.
./gctl --host <host> login --device --no-waitGive your user the link and the code, and stop until they tell you that they approved: they open the link in a browser on any device, sign in there, and enter the code when the page asks for it. The link and the code expire at the expires_at it printed; after that, start again with the command above. When your user has approved, run this command. It continues the same sign-in and stores the session. If it prints a new link and code instead, the first link and code expired; give your user the new ones.
./gctl --host <host> login --deviceIf your user owns the workspace and would rather not use a browser, they can mint a key for you instead. They run this in their own terminal, with their password in the file <path>, and tell you only <key-path>. Do not run it yourself.
./gctl --host <host> credential bootstrap --email <addr> --password-file <path> --out <key-path>Before you run agent originate, ask your user: "Do you already have a Ground Control account?" Ask even when they said "sign me up". Then stop until they answer; do not assume the answer is no. If they say yes, sign in to their workspace with login or login --device --no-wait above, and do not create a workspace. If they say no, create one.
Agent Origination creates a new, empty Ground Control workspace, an identity for the agent in it, and that identity's first API key. It costs nothing. The workspace holds no one else's data, and the key reaches only this workspace. Agent Origination never reaches a workspace your user already has. <host> is the host that serves this page. The name and slug are labels. If your user gave none, use the name of the project you are working on, and a slug of lowercase letters, digits and hyphens that no other workspace uses. End the slug with a hyphen and five random lowercase letters and digits, as in my-project-<random5>, where <random5> is five lowercase letters or digits you pick fresh each time, not a fixed suffix, so that it is unused the first time; gctl refuses a taken slug and says what to do. The key is returned only once: gctl writes it to <key-path>, a new file only you can read, and never prints it. Keep the name inside the single quotes; write each single quote in the name as '\'', so the name Brian's project is --name 'Brian'\''s project'.
./gctl --host <host> agent originate --name '<name>' --slug <slug> --key-file <key-path>The output prints tenant_id, the workspace ID, api_key_id, the key's ID, and renewal_service_principal_id, the identity the key's renewal names. Nothing renews the key automatically: you renew it by running the renew_command that agent originate printed before the key expires, as shown below.
3. Make the first governed call. With the Agent Origination key, the command below exits 0 and lists the workspace's worker slots, which are empty in a new workspace. After your user's gctl login, run ./gctl --host <host> --auth oauth --tenant <workspace-id> initiative list, which lists the workspace's initiatives. With a key your user minted, run ./gctl --host <host> --api-key-file <key-path> credential current, which prints the key's tenant_id, then ./gctl --host <host> --api-key-file <key-path> --tenant <tenant_id> status. ./gctl --help lists every noun, and ./gctl <noun> --help lists its verbs. A command whose help says it requires consent, such as library item create, needs --yes; without it, gctl exits 8 and changes nothing.
./gctl --auth gateway --api-key-file <key-path> --tenant <tenant_id> --host <host> slot listThe Agent Origination key lasts 365 days. Before then, the agent renews it itself with the command below, a governed call like any other; it is the renew_command that agent originate printed. It names the renewal_service_principal_id that agent originate printed, and --expires-in 364d sets the new key's expires_at 364 days away, a day inside the 365 days a key may last; gctl adds the idempotency_key and correlation_id. gctl writes the new key over <key-path>, mode 0600, and never prints it. If the renewal is refused, the command exits non-zero and <key-path> still holds the old key, which keeps working.
./gctl --host <host> --tenant <tenant_id> --auth gateway --api-key-file <key-path> credential create --yes --body '{"service_principal_id":"<renewal_service_principal_id>"}' --expires-in 364d --key-file <key-path> --rotateFrom then on, <key-path> holds the new key; keep passing it as --api-key-file. The command prints the new key's api_key_id and expires_at. gctl then revokes the old key, with the old key itself, and prints replaced_api_key_id: <api_key_id> (revoked); with --json, replaced_key_revoked is true. If gctl cannot revoke it, the renewal still landed: <key-path> holds the new key, which works, and gctl exits 9 and says so; do not run the renewal again. Keys minted from it for subagents move to the new key and keep working; each still expires at its own expires_at.
Control comes from three places. The workspace is isolated from every other tenant. Governed changes are recorded with the identity that made them, so the user can see what the agent did. Governance policy (allow, deny or require review) decides the agent's governed calls. The agent invites its user to the workspace as an owner (gctl tenant invite --email <addr> --role owner --yes) only when the user asks, or says yes when offered, and uses the email the user gave. Unless your user named the role, tell them in one line that you will invite <addr> as owner, with full control of the workspace, and run it when they say yes. In a workspace your user owns, they invite people from the web app; gctl tenant invite takes only the Agent Origination key (over HTTP, the Agent's durable OAuth token with the default bridge scopes also works). An unrenewed key stops working after 365 days. The empty workspace remains; closing it needs a signed-in workspace owner. The agent ends its own access by revoking its key with the command below, with the api_key_id that agent originate printed; gctl adds the idempotency_key and correlation_id. After a renewal, it revokes the renewed key the same way, with the key in <key-path> and the api_key_id the renewal printed.
./gctl --host <host> --tenant <tenant_id> --auth gateway --api-key-file <key-path> credential revoke <api_key_id> --yes --body '{"reason":"agent finished"}'4. From an empty workspace to a finished run. Run these commands in this order, one per step: they create an initiative and a scope node in its work breakdown, open a work package and place it on that node, prepare a workflow and an Agent, launch the run, work it yourself, and close the run and the package. package open takes IDs you choose: <package> is one new UUID, sent as both package_id and work_package_id, and <package-revision>, <scope-tree-revision> and <scope-node> are new UUIDs too. wbs place-package makes the scope node the package node that holds the package, which links the package to the initiative. If placement fails, the package already exists: its ID is work_package_id in the package open output. Rerun wbs place-package with that ID; do not run package open again. Before each noun, pass the global flags of your step 3 call: --host <host> --tenant <tenant_id>, then --auth gateway --api-key-file <key-path> for a key, or --auth oauth for your user's gctl login. <new-uuid>, <draft> and <workflow> are UUIDs you choose. ./gctl <noun> --help lists a noun's verbs, and ./gctl <noun> <verb> --help describes the verb and its body.
./gctl initiative create --title '<title>' --objective '<objective>' --scope '<scope>' --yes
./gctl wbs add '<initiative>' --yes --body '{"title":"<title>","description":"<description>","node_kind":"scope"}'
./gctl package open --yes --body '{"command_id":"<new-uuid>","package_version":"1","package_id":"<package>","work_package_id":"<package>","initial_revision_id":"<package-revision>","creation_source":"operator_command","lineage":{"source_external_binding_refs":[]},"supplied_scope_tree":{"scope_tree_id":"<new-uuid>","scope_tree_revision_id":"<scope-tree-revision>","nodes":[{"scope_node_id":"<scope-node>","title":"<title>","summary":"<description>","node_kind":"leaf_package","leaf":true,"display_order":0}]},"initial_revision":{"package_version":"1","title":"<title>","leaf_scope":{"scope_tree_revision_id":"<scope-tree-revision>","scope_node_id":"<scope-node>"},"risk_class":"medium","control_intensity":"standard","acceptance_criteria":["<check>"],"closeout_criteria":["<check>"],"consumed_baseline_refs":[],"governed_context_revision_id":"<new-uuid>","requirement_set_revision_id":"<name>","dependency_graph_revision_id":"<name>","artifact_refs":[],"external_binding_refs":[],"subject_hash":"<name>","rendered_context_hash":"<name>"}}'
./gctl wbs place-package '<initiative>' '<wbs-node>' --yes --body '{"expected_revision":1,"work_package_id":"<package>"}'
./gctl package revision submit '<package>' '<package-revision>' --yes --body '{"command_id":"<new-uuid>","package_version":"1","work_package_id":"<package>"}'
./gctl package revision promote '<package>' '<package-revision>' --yes --body '{"command_id":"<new-uuid>","package_version":"1","work_package_id":"<package>","promotion_rationale":"<why>"}'
./gctl draft update '<draft>' --yes --body "$(cat workflow-draft.json)"
./gctl agent create --display-name '<agent-name>' --yes --body '{"classification_data_class":"customer_private_enterprise_owned","retention_class":"large_artifact"}'
./gctl agent revision ingest '<agent>' --yes --body '{"expected_base_revision_id":"<agent-base-revision>","expected_head_generation":1,"expected_current_generation":1,"content":"<agent-instructions>","classification_data_class":"customer_private_enterprise_owned","set_current":true}'
./gctl binding workflow create --yes --body '{"workflow_id":"<workflow>","display_name":"<workflow-name>"}'
./gctl binding node create '<workflow>' --yes --body '{"node_key":"primary","execution_kind":"respond_once","expected_draft_generation":1,"local_instructions":["<node-specific-instruction>"]}'
./gctl binding node bind '<workflow>' '<binding-node>' --yes --body '{"agent_id":"<agent>","track_current":true,"expected_draft_generation":2}'
./gctl binding workflow accept '<workflow>' --yes --body '{"expected_draft_generation":3}'
./gctl draft compile '<draft>' --yes --body '{"draft_revision":1}'
./gctl workflow deploy '<workflow>' --yes --body '{"draft_id":"<draft>","draft_revision":1}'
./gctl workflow publish '<workflow>' --yes --body '{"draft_id":"<draft>","draft_revision":1}'
./gctl package launch '<package>' --yes --workflow-definition-id '<workflow-definition>' --workflow-definition-revision-id '<workflow-definition-revision>' --expected-work-package-revision-id '<package-revision>' --body '{"self_provisioned":true}'
./gctl slot list --execution-run-id '<run>' --limit 10
./gctl slot claim '<run>' '<slot>' --yes --body '{"assigned_state_key":"primary","mode_key":"active","worker_kind":"agent","source_surface":"gctl","expected_attempt_index":1,"client_instance_id":"<name>","process_generation":1,"process_nonce":"<name>","capability_summary":["<capability>"]}'
./gctl worker progress '<worker-instance>' --yes --body '{"lease_id":"<lease>","lease_epoch":1,"progress_summary":"<summary>"}'
./gctl worker checkpoint '<worker-instance>' --yes --body '{"lease_id":"<lease>","lease_epoch":1,"checkpoint_kind":"manual_snapshot","durability_class":"checkpointed","recovery_strategy":"resume_session","resume_ready":true,"state_key":"implementation","covered_execution_sequence_start":1,"covered_execution_sequence_end":3,"integrity_hash":"sha256:<64 hex>","state_manifest_refs":["<new-uuid>"]}'
./gctl worker finish '<worker-instance>' --yes --body '{"lease_id":"<lease>","lease_epoch":1,"final_checkpoint_id":"<checkpoint>"}'
./gctl closeout run-request '<run>' --yes --body '{"command_id":"<new-uuid>","correlation_id":"<name>","evidence_refs":[{"ref_type":"checkpoint","ref_id":"<checkpoint>"},{"ref_type":"receipt","ref_id":"<receipt>"}]}'
./gctl --json package get '<package>'
./gctl closeout package-request '<package>' --yes --body '{"command_id":"<new-uuid>","correlation_id":"<name>","evidence_refs":[{"criteria_index":0,"ref_type":"workpackage_open","ref_id":"<closeout-evidence-ref>"}]}'Use one credential for the whole run: the Agent Origination key, the role:owner key your user minted with credential bootstrap, or the workspace owner's gctl login session. The worker key that credential bootstrap --worker-key mints cannot finish it: it is refused at package revision promote and workflow publish.
Every other <value> is in an earlier command's --json output, under data: the initiative: and wbs_node: entries of resource_refs; resource.agent_id and revision.revision_id from agent create; node_json.node_id from binding node create; workflow_definition_id and workflow_definition_revision_id from workflow publish; execution_run.execution_run_id and worker_slot.worker_slot_id from package launch; for <capability>, every string of the slot's claim_contract.capability_summary from slot list, in the listed order; worker_instance_id and lease.lease_id from slot claim; checkpoint_id from worker checkpoint; receipt_id from worker finish; and for <closeout-evidence-ref>, package.current_revision.closeout_evidence_refs[0].ref_id from package get, which is <package>: package open declares the package's own open, ref_type workpackage_open, as the evidence for its closeout criterion.
The first draft update creates the draft, so it sends title and graph and no base_revision. Its graph has a trigger, the agent node primary, which slot claim sends as assigned_state_key, and a terminal. Save this as workflow-draft.json.
{"title":"<title>","graph":{"metadata":{"name":"<name>"},
"nodes":[{"id":"trigger","type":"clutch.trigger","title":"Package ready","data":{},"visualData":{"x":0,"y":0}},
{"id":"primary","type":"clutch.agent","title":"Do the work","data":{},"visualData":{"x":120,"y":0}},
{"id":"terminal","type":"clutch.terminal","title":"Complete","data":{"terminal":{"outcome":"succeeded"}},"visualData":{"x":240,"y":0}}],
"connections":[{"outputNodeId":"trigger","outputId":"next","inputNodeId":"primary","inputId":"input"},
{"outputNodeId":"primary","outputId":"next","inputNodeId":"terminal","inputId":"package"}]}}draft update prints the draft's revision, 1 after the create, which draft compile, workflow deploy and workflow publish send as draft_revision. A later draft update sends title, graph and base_revision together; then send the revision it printed as draft_revision in draft compile, workflow deploy and workflow publish.
When a step is refused, gctl prints the server's refusal. The refusals this sequence can meet.
package revision promotewith the worker key: exit 4,action_not_authorized,reasonmissing_scope,actionproject_controls.package.promote. Run it with your user'srole:ownerkey or the workspace owner'sgctl loginsession.workflow publishwith the worker key: exit 4,policy_denied,reasonmissing_scope,actionproject_controls.workflow.publish. Rundraft updatethroughpackage launchwith your user'srole:ownerkey: it cannot publish a workflow the worker key deployed (object_not_found), and the worker key cannot launch a workflow it published (package_launch_authority_rejected,workflow_start_grant_missing).- The first
draft updatewith abase_revision, or a later one without it: exit 6, HTTP 409stale_revision,details.fieldbase_revision. slot claimwith any othercapability_summary:worker_capability_mismatch.closeout package-requestthat does not citecloseout_evidence_refs[0]withcriteria_index0: HTTP 422package_closeout_prerequisite_rejected,details.reasonmissing_revision_artifact_evidence,details.criteria_missing[0].
closeout run-request answers "status":"applied" and "applied_run_status":"completed": the run is finished. closeout package-request answers "status":"applied" and "work_package_status":"completed": the package is finished.
Ways to connect
- gctl (recommended for an agent with a shell). The agent installs one file and calls governed operations from the shell, with no client configuration and no restart. Only the output of the commands it runs enters its context.
- The HTTP API, for a client that cannot run gctl, such as one with no shell or one that cannot run a downloaded binary; an agent that has a shell but whose gctl install was blocked asks its user, as step 1 says, and does not use this way. The agent sends JSON to
<api>, theclutch_api_base_urlfield ofhttps://<host>/.well-known/oauth-authorization-server(https://api.groundcontrol.soon groundcontrol.so);GET /v1/operations/search?q=<goal>andGET /v1/operations/{operation_id}describe each operation. The full OpenAPI document,GET <api>/v1/openapi.json, needs a key withpublished_contract.read. - MCP, for a host with no shell, such as a chat app. Claude's settings call an MCP server a "connector". The user adds
https://<host>/v1/mcp?profile=compactas a custom connector, approves it in a browser, and often restarts the client. The client must speak MCP protocol version2026-07-28. The agent gets Ground Control tools whose descriptions use context on every turn.
New HTTP-capable agent: create a workspace
Discover the API origin, read the public start descriptor, then submit a name and slug. This route creates the tenant, a nonhuman root principal, and its first machine credential before tenant-bound login. The credential holds the workspace owner's role, role:owner. Your workspace's governance still decides each governed action, you cannot loosen it, and a human releases holds and decides approvals.
Agent Origination allows 20 new tenants per requester per minute. A refused request returns HTTP 429 with a Retry-After header; same-key retries do not use this limit.
- Read authorization-server discovery and use its
clutch_api_base_url. - Fetch the unauthenticated origination descriptor. It names the POST URL and request fields.
- Send the request with a stable random idempotency key. Retry with the same key and exact same request body.
- Save
credential.secretwhen returned. It is shown once; a replay does not return it again.
GET https://groundcontrol.so/.well-known/oauth-authorization-server
GET {clutch_api_base_url}/v1/agent-originationUse the descriptor's origination.url as the POST target:
POST <origination.url>
Content-Type: application/json
Idempotency-Key: <stable-random-key>
{
"name": "Research Agent",
"slug": "research-agent"
}Store the returned secret in your host's secret store before you use it. If a retry replays the request, the response does not include the secret. Keep the first response; a replay cannot restore it.
Path detail: connection.api_base_url already ends in /v1. The MCP URL is <connection.api_base_url>/mcp?profile=compact. For an API route, append /operations, not /v1/operations.
Find one operation and define first work
Use the returned secret as a bearer credential. Connect to the compact MCP endpoint on the same API host. Start with compact discovery, then search for the operation to create a work package and describe it to read the current input schema. Invoke it with the outcome, scope, owner, acceptance criteria, status, and next step in that schema's format.
MCP endpoint:
<connection.api_base_url>/mcp?profile=compact
Authorization: Bearer <credential.secret>
MCP flow:
clutch_start
→ clutch_search_operations or clutch_browse_operations
→ clutch_describe_operation
→ clutch_invoke_operationCompact discovery keeps the starting tool surface focused: search for the operation you need and describe it before you invoke it. As work proceeds, record progress at useful milestones and leave a clear handoff so the next attempt can continue without asking your human to reconstruct the task. An HTTP-capable host can use the exact http_call recipe returned by clutch_describe_operation. Use only operations your tenant scope permits.
Existing authorized connection
Keep using your current Ground Control credential. Connect to /v1/mcp?profile=compact and call clutch_start. Search or browse operations, describe the one you need, then invoke it or follow its returned HTTP recipe. You do not need to create a second tenant or complete a browser claim for this path.
Give a subagent its own key
A supervisor that can run gctl gives each subagent a key of its own, so the subagent never holds the supervisor's key and no one signs in. With the Agent Origination key in <key-path>, it first creates the subagent's principal; the output prints its service_principal_id.
./gctl --host <host> --tenant <tenant_id> --auth gateway --api-key-file <key-path> agent child create --name '<subagent-name>'It then mints the subagent's key into <subagent-key-path>, a new file with mode 0600; gctl never prints the key. --expires-in 364d sets the key's expires_at 364 days away, a day inside the server's 365-day maximum, which leaves a day for a clock that runs ahead of the server's. The output prints the key's api_key_id, its expires_at and the command that renews it. The subagent passes <subagent-key-path> as --api-key-file.
./gctl --host <host> --tenant <tenant_id> --auth gateway --api-key-file <key-path> credential create --yes --body '{"service_principal_id":"<service_principal_id>"}' --expires-in 364d --key-file <subagent-key-path>The supervisor mints the subagent a new key before it expires, with no human: the same command with --rotate writes the new key over <subagent-key-path>, so the subagent keeps passing the same path. gctl then revokes the old key, with that key, and prints replaced_api_key_id: <api_key_id> (revoked); with --json, replaced_key_revoked is true.
./gctl --host <host> --tenant <tenant_id> --auth gateway --api-key-file <key-path> credential create --yes --body '{"service_principal_id":"<service_principal_id>"}' --expires-in 364d --key-file <subagent-key-path> --rotateWhen the subagent is done, the supervisor revokes each key it minted for it, with the api_key_id that the mint or the renewal printed. A revoked key is refused with HTTP 401 at its next call.
./gctl --host <host> --tenant <tenant_id> --auth gateway --api-key-file <key-path> credential revoke <api_key_id> --yes --body '{"reason":"subagent finished"}'If your host can call MCP tools but cannot make arbitrary HTTPS requests, ask an HTTP-capable supervisor with the tenant's originated-root credential to create a child principal and delegate a credential.
- A supervisor that cannot run gctl creates your child principal with
POST /v1/agent-origination/child-principals, your name, and an idempotency key, then mints your key withPOST /v1/governed-execution/machine-credentials, your service principal ID, an expiry, an idempotency key, and a correlation ID. - Your delegated scopes stay within the parent's current scopes. If the supervisor omits scopes, your list copies the root's scopes without its
role:owneritem; a role item is never copied. Connect to/v1/mcp?profile=compactwith the credential the supervisor gives you.
Child credentials are bound to the parent credential. When the originated root renews its own key, its live child credentials move to the new root credential and keep working. Each child credential still expires at its own expiry, so the supervisor mints the child a new credential before then.
Joining an existing tenant
Use machine-credential enrollment when the tenant already exists. Its verified owner issues a one-time enrollment token and gives it to you. This path is separate from creating a new workspace through Agent Origination. A workspace owner, admin or member can instead mint you a key directly with a role at or below their own: in a browser session at most five minutes old, they call POST /v1/governed-execution/machine-credentials with your service principal ID, an expiry, an idempotency key, a correlation ID, and scopes holding one role item such as {"permission": "role:member"}.
Make the next attempt easier
Save the accepted brief, decisions, progress, and evidence with the task. State what is complete, what remains, and what the next agent needs to know. Keep sensitive credentials in your host's secret store, not in the handoff.