Agent credentials and CI tokens
This page is for developers who run an agent, a service or a CI job that reads or changes instructions without a person signed in. You will create an agent credential (API key), trade it for a token, use the token, and rotate or revoke it.
Plans On Pro, Team, and Enterprise
An agent credential is an OAuth client of its own, in your organization: a client id and a secret. Whoever holds the secret asks the token URL for a token with the client-credentials grant, and calls the MCP server with it. The server sees the agent, not the person who made it.
Before you start
- Who can do this: an owner or an admin of the organization creates, rotates and revokes credentials, as a person (never with an agent's token). Anyone in the organization, agents included, can list them.
- Plan: agent credentials are not on every plan. How many active credentials each plan keeps:
Plans Pro 10 · Team 100 · Enterprise unlimited
- What you need: the editor with Developer mode on, or the CLI (
npm i -g instruction.md, 0.11.0 or later) signed in withinstruction login.
A credential doesn't take a seat. Revoked credentials don't count towards the limit.
Create a credential in the editor
Open Developer ▸ API keys
With Developer mode on, the side bar shows Developer. Choose Developer ▸ API keys. The page lists the organization's agents, or says No agents yet.
Name the agent and choose Create credential
Type a name in The agent's name, such as
deploy-bot, and choose Create credential. A name is unique among the organization's active credentials.Copy the secret and the token URL
The page shows the credential, such as deploy-bot's credential, with its client id, the Secret and the Token URL, each with a copy button. Keep the secret in the agent's secret store now: it is shown this once. Then choose I've kept it.
A credential made in the editor is of kind agent, has the scope instructions:read only, and is a Reader in the organization's default workspace. For write or publish scopes, another kind or another role, create it with the CLI or the orgs_agents_create tool.
Create a credential with the CLI
instruction agents create needs the permission to administer your organizations. Without it, the CLI offers to sign you in again for it on a terminal; elsewhere it stops and says to run instruction login --admin once.
instruction login --admin
instruction agents create ci --org acme --kind service --scopes read,write,publish --workspace-role maintainer The CLI prints the credential once:
agent agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C (ci) in acme
client_id: agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C
client_secret: <client secret> <- shown once; store it now (INSTRUCTION_MD_CLIENT_SECRET)
token_url: https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token
audience: https://instruction.md/mcp
scopes: instructions:publish instructions:read instructions:write
next: instruction connect --host agentd --agent agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C --org acme <uri> The flags:
| Flag | Values | Default | Effect |
|---|---|---|---|
NAME |
up to 80 characters | required | The agent's name, unique among the organization's active credentials (case does not count). Runs of spaces become one, and a longer name is cut to 80. |
--org SLUG |
an organization's slug or id | your personal organization | The organization the credential belongs to. Pass it for any organization other than your personal one. |
--kind |
agent, service |
agent |
A label on the credential and in its token's actor_type claim. The two kinds have the same rights. |
--scopes |
read, write, publish, comma-separated |
read |
Each word becomes instructions:<word>. The full names are accepted too. |
--workspace-role |
reader, contributor, maintainer |
none | A role in the organization's default workspace. admin is refused. |
--json |
The whole answer as JSON: agent, clientId, clientSecret, tokenUrl, audience, issuer. |
A read-only agent that is a Reader in the default workspace:
instruction agents create support-bot --org acme --workspace-role reader The MCP tool is orgs_agents_create (arguments orgId, name, kind, scopes, workspaceRole, idempotencyKey). Sent again with the same idempotencyKey, it answers the agent it made, without the secret: rotate it for a new one.
Get a setup snippet
instruction connect --agent ID prints the configuration a host needs for an existing credential: its client id, the token URL and its scopes, never the secret (that was shown once). --host names the host, such as agentd, sdk, ci, claude-code or codex; the default is generic. Hosts that sign a person in themselves, such as claude and chatgpt, don't use the credential, and the snippet says so.
instruction connect --host ci --agent agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C --org acme instruction://acme/support-agent@stable What the credential holds
| Field | Value on instruction.md |
|---|---|
| Client id | The agent's id, agt_ and a ULID. |
| Client secret | Shown once, at creation and at each rotation. instruction.md doesn't keep it: the identity provider does. |
| Token URL | https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token |
| Audience | https://instruction.md/mcp, added to every token. You don't send it. |
| Scopes | The ones it was created with, written into every token. A token never carries more. |
The CLI prints INSTRUCTION_MD_CLIENT_SECRET beside the secret. That is the variable the samples on these pages read it from. Keep it in your CI's or your platform's secret store, never in a repository or an instruction.
Get a token
Ask the token URL with the client-credentials grant. No scope or audience parameter is needed.
TOKEN=$(curl -s -X POST 'https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token' \
-d grant_type=client_credentials \
-d client_id='agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C' \
-d client_secret="$INSTRUCTION_MD_CLIENT_SECRET" | jq -r .access_token) {
"access_token": "eyJhbGciOiJSUzI1NiIs…",
"expires_in": 300,
"token_type": "Bearer",
…
} A token lasts five minutes (expires_in: 300), and there is no refresh token. Ask for a new one before it lapses. A job shorter than five minutes asks once.
Use the token
The instruction CLI and instruction agents take a token in INSTRUCTION_MD_TOKEN (or --token). A token given this way is used as it is, never refreshed. The full list of variables is in Environment variables and files.
export INSTRUCTION_MD_TOKEN="$TOKEN"
instruction whoami
instruction pull instruction://acme/support-agent@stable --out instruction.md From a raw MCP client, send it as a bearer token. The server speaks MCP 2026-07-28 only: every request carries its protocol version.
curl -s https://instruction.md/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-H 'mcp-protocol-version: 2026-07-28' \
-H 'mcp-method: resources/read' \
-H 'mcp-name: instruction://acme/support-agent@latest' \
-H "authorization: Bearer $TOKEN" \
-d '{"jsonrpc":"2.0","id":1,"method":"resources/read","params":{"uri":"instruction://acme/support-agent@latest","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"ci","version":"1"},"io.modelcontextprotocol/clientCapabilities":{}}}}' The SDK helper in @instruction.md/agents takes a function that answers a token before each read, so it can ask for a new one when the old one is about to expire:
import { follow } from "@instruction.md/agents/agent";
const TOKEN_URL = "https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token";
let cached: { token: string; until: number } | null = null;
// A new token when the one in hand has less than 30 seconds left: they last five minutes, with no refresh token.
async function token(): Promise<string> {
if (cached && Date.now() < cached.until) return cached.token;
const r = await fetch(TOKEN_URL, {
method: "POST",
body: new URLSearchParams({
grant_type: "client_credentials",
client_id: process.env.INSTRUCTION_MD_CLIENT_ID!,
client_secret: process.env.INSTRUCTION_MD_CLIENT_SECRET!,
}),
});
if (!r.ok) throw new Error(`token request refused: HTTP ${r.status}`);
const b = (await r.json()) as { access_token: string; expires_in: number };
cached = { token: b.access_token, until: Date.now() + (b.expires_in - 30) * 1000 };
return cached.token;
}
const ins = await follow("instruction://acme/support-agent@stable", { token });
console.log(ins.text); How an MCP client authenticates in general, people and agents, is in Sign-in, scopes and tokens.
Use it in CI
Keep the client id as a variable and the secret as a secret of the pipeline. Ask for a token in the step that needs it.
# .github/workflows/instruction.yml (a step of a job)
- name: Read the stable instruction
env:
INSTRUCTION_MD_CLIENT_ID: ${{ vars.INSTRUCTION_MD_CLIENT_ID }}
INSTRUCTION_MD_CLIENT_SECRET: ${{ secrets.INSTRUCTION_MD_CLIENT_SECRET }}
run: |
export INSTRUCTION_MD_TOKEN=$(curl -s -X POST 'https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token' \
-d grant_type=client_credentials -d client_id="$INSTRUCTION_MD_CLIENT_ID" \
-d client_secret="$INSTRUCTION_MD_CLIENT_SECRET" | jq -r .access_token)
npx -y instruction.md pull instruction://acme/support-agent@stable --delivered --out AGENTS.md A credential with write changes a draft as suggestions by default. instruction push --to as an agent saves its change as suggestions a maintainer accepts, and says so. To release the draft people accepted:
# a change from the repository: lands as suggestions a maintainer accepts
instruction push instruction.md --to acme/support-agent
# release the draft people accepted (needs "Agents may publish" and the publish scope)
instruction publish acme/support-agent --message "Release from CI" --yes instruction publish and instruction revoke ask first. Without a terminal, pass --yes, or they stop with exit code 7 and change nothing. Validating, testing and gating the stable ref from a pipeline are on Publish and check from CI.
What an agent can and can't do
What a call may do is the lowest of three things: the token's scopes, the agent's role on the instruction, and the organization's policy.
| Scope | At most |
|---|---|
instructions:read |
Read the versions it may read. |
instructions:write |
Edit drafts it may edit, as suggestions by default. |
instructions:publish |
Release versions, if the policy lets agents publish. |
- Role: an agent is a member of the organization, so it reads the instructions visible to the organization and public ones.
--workspace-rolegives it a role in the default workspace. For another workspace, give it a role there withorgs_workspaces_roles_setand itsagt_id. An agent is at most a Maintainer. - Policy: by default an organization doesn't let agents publish. An admin turns on Agents may publish (policy key
agentPublish) in Settings ▸ Security. Until then a release is refused, whatever the scopes. Approving a proposal follows the policy keyaiAutoPublish, and merging one follows either key. Widening who reads an instruction, such as making it public or making a read link, followsagentSharing. Both keys are on Organization policy, roles and permissions. - Never: an agent never administers. No credential has
org:adminorinstructions:admin. Every tool that changes the organization (members, invitations, workspaces and their roles, policy, keys, agent credentials, billing) and the activity and audit tools are hidden from agent and service tokens, and the server refuses them on every call too. An agent can't make, rotate or revoke a credential. It can still call the organization's read tools a member can, such asorgs_members_list,orgs_workspaces_listandorgs_agents_list.
Rotate a secret
Rotating gives the credential a new secret. The old secret stops working at once. Tokens already issued keep working until they expire, at most five minutes.
In the editor, choose Rotate secret on the agent's row, then Rotate. The new secret is shown once, as at creation.
instruction agents rotate agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C --org acme The CLI shows what the server asks, and waits:
Rotate ci's secret?
The current secret stops working at once; the agent needs the new one.
Go ahead? [y/N] y
agent agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C in acme
client_id: agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C
client_secret: <new client secret> <- shown once; store it now (INSTRUCTION_MD_CLIENT_SECRET)
token_url: https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token
next: instruction connect --host agentd --agent agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C --org acme <uri> Without a terminal, pass --yes, or it stops with exit code 7 and changes nothing. The new secret is printed as at creation, without the audience and scopes lines; the client id stays the same. The MCP tool is orgs_agents_rotate, which asks for confirmation (needs_confirmation, then the same call with its confirmToken).
Revoke a credential
Revoking can't be undone. The credential gets no new tokens, and it leaves the organization and its workspaces. It stays in the activity log.
In the editor, choose Revoke on the agent's row, then Revoke again.
instruction agents revoke agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C --org acme --yes With --yes the CLI still prints what the server said would happen (on stderr), then the result. On a terminal without --yes it asks Go ahead? [y/N] first.
Revoke ci?
It gets no new tokens; the ones it holds expire within five minutes.
Its memberships are removed.
revoked agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C: no new tokens; the ones it holds expire within five minutes The CLI's line says the tokens it holds expire; in fact the server already refuses a call made with one: "this agent credential is not one of ours, or was revoked". The token itself expires within five minutes. Revoking a revoked credential changes nothing. To bring the agent back, create a new credential.
See when a credential was last used
Each row in Developer ▸ API keys says the kind, the scopes and last used with a time, or not used yet. Every call an agent makes updates it. instruction agents list lists the active credentials:
instruction agents list --org acme agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C service ci instructions:publish,instructions:read,instructions:write active
agt_01JX7Q4B8C2D6E0F3G7H1J5K9M agent support-bot instructions:read active With --json, each agent also has clientId, issuer, state, createdAt, createdBy and createdByName, and, once set, lastSeenAt, rotatedAt and workspaceRole. instruction agents with no command is instruction agents list. Creating, rotating and revoking are recorded as agent.created, agent.rotated and agent.revoked in the audit trail.
Why "instruction agents create" and "instruction agents run" differ
instruction agents is one command name for two tools:
list,create,rotateandrevokeare theinstructionpackage's own. They manage your organization's agent credentials.follow,install,run,check,connect,login,whoami,mcp,helpand--version, and the commands that moved (hook,acp,turn,sync,fleet,apply,doctor,accounts,credential,signin), are handed to@instruction.md/agents:instruction-agentsif it is installed, elsenpx --yes @instruction.md/agents. Any other word is refused as an unknown agents command.
So instruction agents create makes a credential, and instruction agents run starts agents on a machine of yours. The runner signs in with instruction agents login or INSTRUCTION_MD_TOKEN: see The runner. Every command of both is on instruction command reference and instruction-agents command reference.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
orgs_agents_create: limit_reached: agents need the Pro plan or above |
The organization's plan has no agent credentials. Without --org, the CLI uses your personal organization. |
Pass --org, or change the plan on Plans. |
limit_reached: this plan keeps N agent(s); revoke one or upgrade |
The plan's active credentials are all in use. | Revoke one you no longer use, or change the plan. |
conflict: an agent with that name exists |
An active credential has that name. | Choose another name, or revoke the old one first. |
validation: unknown scopes: instructions:… |
A scope other than read, write or publish. | Use --scopes read,write,publish or a part of it. |
validation: an agent is at most a maintainer: agents never administer |
--workspace-role admin. |
Use maintainer or lower. |
`instruction agents create` administers an organization… Run `instruction login --admin` once |
Your sign-in lacks the permission to administer organizations, and there is no terminal to ask. | Run instruction login --admin, then the command again. |
forbidden: this organization doesn't let agents release versions (policy agentPublish); suggest the change and ask a maintainer |
Agents may publish is off. | An admin turns it on in Settings ▸ Security, or a person publishes. |
scope_required: this needs a wider scope on your token |
The credential's scopes don't reach the call. | Create a credential with the scope it needs. Scopes can't be added to an existing one. |
forbidden: this agent credential is not one of ours, or was revoked |
The credential was revoked. | Create a new one. |
not_found: agent not found on rotate |
The id is wrong, or the credential was revoked. | Check instruction agents list --org SLUG. |
| Still stuck | Contact support. |
More messages and fixes are on Troubleshooting.
Questions
How do I get a non-interactive token for CI?
Create a credential with instruction agents create NAME --org SLUG --kind service, keep its secret in the pipeline's secrets, and ask the token URL for a token with the client-credentials grant in the step that needs it. Put the token in INSTRUCTION_MD_TOKEN for the CLI. See Use it in CI.
What is the difference between instruction and instruction agents, and which package do I install?
Install instruction.md (npm i -g instruction.md) for writing, checking, releasing and agent credentials. instruction agents hands following, installing and running agents to @instruction.md/agents, fetched with npx when it isn't installed. See the section above.
I lost the secret. Can I see it again?
No. instruction.md doesn't keep it. Rotate the credential to get a new secret, and update the agent; the old secret stops working at once.
Can I change a credential's scopes or kind?
No. Create a new credential with the scopes and kind you need, move the agent to it, then revoke the old one. Its workspace roles can be changed with orgs_workspaces_roles_set.
Does an agent's write change the draft directly?
Not by default. An agent's edits land as suggestions a maintainer accepts. A raw instructions_draft_edit or instructions_draft_replace call with asSuggestion: false edits directly, if the agent's role allows it.