لم تُترجم هذه الصفحة بعد.

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 with instruction login.

A credential doesn't take a seat. Revoked credentials don't count towards the limit.

Create a credential in the editor

  1. 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.

  2. 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.

  3. 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.

Developer ▸ API keys: the secret is shown once, when the credential is created or rotated.

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.

A CI credential that may read, write and publish
instruction login --admin
instruction agents create ci --org acme --kind service --scopes read,write,publish --workspace-role maintainer

The CLI prints the credential once:

Output
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:

A reader
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.

A CI snippet for the credential
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.

Client-credentials token request
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)
The answer
{
  "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.

The CLI as the agent
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.

One resources/read with curl
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:

TypeScript: follow an instruction as the agent
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 Actions
# .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:

Propose, then release
# 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-role gives it a role in the default workspace. For another workspace, give it a role there with orgs_workspaces_roles_set and its agt_ 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 key aiAutoPublish, and merging one follows either key. Widening who reads an instruction, such as making it public or making a read link, follows agentSharing. Both keys are on Organization policy, roles and permissions.
  • Never: an agent never administers. No credential has org:admin or instructions: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 as orgs_members_list, orgs_workspaces_list and orgs_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.

Rotate with the CLI
instruction agents rotate agt_01JX7Q2M4N8R5T6V9W0Y3Z1A2C --org acme

The CLI shows what the server asks, and waits:

Output
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.

Revoke with the CLI
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.

Output
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:

List
instruction agents list --org acme
Output
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, rotate and revoke are the instruction package's own. They manage your organization's agent credentials.
  • follow, install, run, check, connect, login, whoami, mcp, help and --version, and the commands that moved (hook, acp, turn, sync, fleet, apply, doctor, accounts, credential, signin), are handed to @instruction.md/agents: instruction-agents if it is installed, else npx --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.

Last checked against the product:

Was this page helpful? Report a problem