Agent Accounts - Runlayer

An agent account is the identity Runlayer gives an agent. Instead of running under a person’s login or a shared service credential, the agent is its own principal in your workspace, with its own policies, its own delegations from the people it works for, its own tokens, and its own audit trail. That changes what you can do with an agent:

Scope it on its own terms. Policies and identity attributes apply to the agent itself, so a read-only reporting agent and a deploy agent are governed separately even when the same team built both.
Make authority explicit. Every token says whose authority the agent is using: its own, or a specific user’s, granted through a delegation that user can see and revoke. When it acts for a user, policy is the intersection of both.
Follow every action back to it. Audit rows and session activity name the agent, the user it acted for, and the token it used. Runs of Runlayer-hosted agents add the run ID.
Turn it off precisely. Revoke one token, one delegation, one connection, or the whole account. No person loses access in the process.

What is an Agent Account?

An agent account is a principal in your Runlayer workspace, alongside users and groups. You can name it in policies, give it identity attributes, attach connectors to it, and let users delegate to it. The agent proves it is that principal with a Client ID and Client Secret issued on creation, and calls MCP tools through the Runlayer proxy with the tokens it mints: an M2M token for its own authority, or an OBO token for a user’s delegated authority.

Why agents need their own identity

Teams usually start with one of two shortcuts, and both break down the moment more than one agent exists. The agent runs as the person who set it up. A Slack support agent and a Jira cleanup agent both authenticating as the admin who configured them look identical in every log and every policy decision. Tightening one tightens the other, and the only way to stop either is to lock the admin out. All agents share one service account. Six agents behind one “automation” credential means nobody can say which one touched production, a policy for one applies to all, and rotating the secret takes every agent down at once. An agent account gives each agent a principal of its own, so scope, consent, evidence, and shutdown all land on the agent that earned them. Instances stay distinguishable too: Runlayer-hosted agents carry a run ID on every tool call, and every token an agent mints is registered individually, so one token can be revoked without touching the others, and can be bound to the caller’s key with DPoP.

Identity at every layer

Layer	What identifies it	What you can do with it
Agent account	Client ID, identity attributes	Assign policies, disable, rotate credentials
Delegation	Delegating user and agent, expiry	See who granted authority, revoke per user
Session grant	Grantor and server	See whose upstream credentials are used
Token	Registered individually at issuance, its `aud` scope, optional DPoP key binding	Revoke one token, scope it to servers, bind it to a key
Run (hosted Agents)	Run ID and agent ID	Correlate every tool call to one execution
Audit row	Actor, delegating user, agent, run	Export evidence to your SIEM

Token Types

Agent accounts can obtain two types of access tokens depending on their use case:

M2M Token (Machine-to-Machine)

Use M2M tokens when your agent account operates autonomously without a specific user context.

The agent acts under its own authority; the account’s policies are the whole boundary
Only agent account-level policies are enforced
Ideal for background jobs, scheduled tasks, and agents nobody is sitting in front of

OBO Token (On-Behalf-Of)

Use OBO tokens when your agent account acts on behalf of a specific user.

The agent acts under a user’s delegated authority; that user can see and revoke the delegation
Intersection of agent account and user policies are enforced
Requires an active delegation from the user to the agent account
Ideal for work a specific person asked for, where the audit trail must name both

How OBO Works

The complete On-Behalf-Of flow, end to end: a one-time delegation from the user, a two-step token flow (mint an agent token, then exchange it for an OBO token per RFC 8693), and a proxied MCP call that enforces both parties’ policies and resolves OAuth credentials through session grants. Each concept in the diagram is covered below: authentication, delegations, session grants, and policies. For copy-paste code, see the Agent Account Authentication Recipes.

Authentication

Agent accounts authenticate using OAuth 2.0: the Client Credentials grant for M2M tokens, plus an RFC 8693 token exchange for OBO tokens. The token endpoint returns a JWT that you include in the Authorization header of all API requests. The examples below use Bearer tokens; accounts with Require DPoP on need a proof on every request (see the DPoP recipes).

Getting an M2M Token

# Get M2M token (agent-only, no user context)

TOKEN_RESPONSE=$(curl -s -X POST 'https://your-runlayer-instance.com/api/v1/oauth/token' \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=your-client-id" \
  --data-urlencode "client_secret=your-client-secret" \
  --data-urlencode "resource=https://your-runlayer-instance.com/api/v1/proxy/your-server-id/mcp")

ACCESS_TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.access_token')

echo "M2M Token: ${ACCESS_TOKEN:0:50}..."
# Token valid for 1 hour

resource scopes the token to the server it calls. Accounts with Enforce server scoping on require it.

Getting an OBO Token

To get an OBO token, you need one of:

A user UUID from an active delegation
A user email from an active delegation
A WorkOS user access token (RFC 8693 compliant)

Accounts with Strict Mode enabled reject all three of these subject types. They only accept an id_token minted by the account’s own login app, and every exchange must name its target servers via resource.

Getting an OBO token is a two-step flow: mint an agent token with client_credentials (the same call as the M2M example above), then exchange it for an OBO token via RFC 8693 token exchange. The agent token is cacheable and can be reused across many user exchanges, and the client_secret never travels on the per-user exchange call. Pass the same resource on both calls: an exchange can’t widen past the agent token’s scope.

RESOURCE="https://your-runlayer-instance.com/api/v1/proxy/your-server-id/mcp"

# Step 1: mint agent token (same call as M2M)
AGENT_RESPONSE=$(curl -s -X POST 'https://your-runlayer-instance.com/api/v1/oauth/token' \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=your-client-id" \
  --data-urlencode "client_secret=your-client-secret" \
  --data-urlencode "resource=$RESOURCE")
AGENT_TOKEN=$(echo "$AGENT_RESPONSE" | jq -r '.access_token')

For step 2, pick the subject_token form that matches what your system stores:

USER_ID="user-uuid-from-delegation"

TOKEN_RESPONSE=$(curl -s -X POST 'https://your-runlayer-instance.com/api/v1/oauth/token' \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "actor_token=$AGENT_TOKEN" \
  --data-urlencode "actor_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "subject_token=$USER_ID" \
  --data-urlencode "subject_token_type=urn:runlayer:token-type:user-id" \
  --data-urlencode "resource=$RESOURCE")

OBO_TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.access_token')

USER_EMAIL="user@example.com"

TOKEN_RESPONSE=$(curl -s -X POST 'https://your-runlayer-instance.com/api/v1/oauth/token' \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "actor_token=$AGENT_TOKEN" \
  --data-urlencode "actor_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "subject_token=$USER_EMAIL" \
  --data-urlencode "subject_token_type=urn:runlayer:token-type:user-email" \
  --data-urlencode "resource=$RESOURCE")

OBO_TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.access_token')

USER_ACCESS_TOKEN="user-workos-access-token"

TOKEN_RESPONSE=$(curl -s -X POST 'https://your-runlayer-instance.com/api/v1/oauth/token' \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "actor_token=$AGENT_TOKEN" \
  --data-urlencode "actor_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "subject_token=$USER_ACCESS_TOKEN" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "resource=$RESOURCE")

OBO_TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.access_token')

The agent now acts with the intersection of agent and user policies.

Migrating from the client_credentials OBO shortcut: earlier versions documented passing subject_token / subject_token_type directly on the client_credentials grant. That shape is still accepted for backward compatibility but deprecated — switch to the two-step flow: mint an agent token with client_credentials, then exchange it with grant_type=urn:ietf:params:oauth:grant-type:token-exchange (agent token in actor_token, user identity in subject_token, per RFC 8693 §2.1).

Scoping a token to specific servers (optional)

Pass one or more RFC 8707 resource parameters (the MCP server URL) on the client_credentials or token-exchange call to scope the minted token to those servers. The server records the targets in the token’s aud claim:

# Same client_credentials call as above, with one `resource` per target server.
# Example: scope the token to two servers, 3f6a2b1e-… and b81f0c2d-….
TOKEN_RESPONSE=$(curl -s -X POST 'https://your-runlayer-instance.com/api/v1/oauth/token' \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=your-client-id" \
  --data-urlencode "client_secret=your-client-secret" \
  --data-urlencode "resource=https://your-runlayer-instance.com/api/v1/proxy/3f6a2b1e-8c4d-4e5f-9a7b-2c1d0e9f8a7b/mcp" \
  --data-urlencode "resource=https://your-runlayer-instance.com/api/v1/proxy/b81f0c2d-5a6e-4f3b-8d9c-7e6f5a4b3c2d/mcp")

The same parameter works on the token-exchange call. To scope an on-behalf-of (OBO) token to a plugin, pass the plugin’s MCP URL as resource: https://your-runlayer-instance.com/api/v1/proxy/plugins/<plugin-id>/mcp, or https://your-runlayer-instance.com/mcp for the Runlayer Plugin. The token then works on that plugin’s endpoint only, not on the servers behind the plugin, which it reaches through the plugin. You can mix plugins and servers in one request. When enforcement is on, scope the client_credentials agent token to the same plugin before exchanging it: an exchange can’t widen past the agent token’s scope. The agent token can’t call the plugin by itself, because plugins serve tools as a user; only the exchanged token can. Strict Mode accounts can’t scope a token to a plugin yet: a request that names a plugin gets invalid_target.

The aud claim is narrowed to the servers and plugins the principal can access. Whether the proxy enforces it is controlled per agent account by the Enforce server scoping setting — see Resource Scoping Enforcement. Without enforcement, omitting resource mints a token with no aud, accepted everywhere the principal’s policies allow (unchanged behavior).

Calling MCP Tools

Once authenticated, you can call MCP tools through the Runlayer proxy using your access token. The proxy exposes a standard MCP Streamable HTTP transport endpoint at /api/v1/proxy/{server_id}/mcp.

# Call MCP tool through the Runlayer proxy
# Use $ACCESS_TOKEN (M2M) or $OBO_TOKEN

curl -X POST "https://your-runlayer-instance.com/api/v1/proxy/your-server-id/mcp" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_context",
      "arguments": {
        "query": "project structure"
      }
    },
    "id": 1
  }'

The proxy endpoint uses the MCP Streamable HTTP transport. You can also use any MCP SDK client (such as the Vercel AI SDK, OpenAI Agents SDK, or Google ADK) pointed at the https://your-runlayer-instance.com/api/v1/proxy/{server_id}/mcp URL.

Resource Scoping Enforcement

Scoping a token records the target servers or plugins in the token’s aud claim. Whether the proxy enforces that scope is a per–agent-account setting, Enforce server scoping, in Settings → Agent Accounts → (account) → Settings. When enforcement is on, the proxy rejects an aud-bearing token used against a server or plugin outside its aud with 403 invalid_target. This confines a leaked or over-shared token to exactly the servers or plugins it was scoped to, below the account’s usual policy ceiling.

Off by default — opt in per account. Enforcement is disabled until an admin turns it on for a specific agent account, so no account is forced to scope its tokens by an upgrade.
When on, resource is required. The token endpoint rejects a token request that doesn’t name at least one server or plugin (invalid_target), so every token this account issues is scoped. (Per RFC 8707 §2, an authorization server may require resource indicators.)
Scope a token to every server it will call. A token scoped to server A cannot call server B, even if the account’s policies allow B.
A plugin scope covers the plugin endpoint only. A token scoped to a plugin works on that plugin’s endpoint and is rejected on the servers behind it, which it reaches through the plugin.
Aggregate endpoints reject scoped tokens. The agent-account aggregate MCP and skill endpoints fan out beyond a single named resource, so a scoped (aud-bearing) token is rejected there.

For example, with enforcement on and a token scoped to server 3f6a2b1e-… (see the scoping example above):

# In the token's aud — allowed (normal policy checks still apply)
curl -X POST "https://your-runlayer-instance.com/api/v1/proxy/3f6a2b1e-8c4d-4e5f-9a7b-2c1d0e9f8a7b/mcp" \
  -H "Authorization: Bearer $ACCESS_TOKEN" ...

# Any other server — rejected with 403
curl -X POST "https://your-runlayer-instance.com/api/v1/proxy/b81f0c2d-5a6e-4f3b-8d9c-7e6f5a4b3c2d/mcp" \
  -H "Authorization: Bearer $ACCESS_TOKEN" ...

403 response

{ "detail": "invalid_target: token audience does not include this resource" }

A token request that omits resource fails at the token endpoint instead:

400 response

{
  "error": "invalid_target",
  "error_description": "invalid_target: this agent account requires one or more `resource` indicators naming the server(s) the token may access"
}

Turning enforcement on takes effect immediately, including for tokens already issued: any aud-bearing token used outside its aud starts getting rejected, and new token requests must include resource. Confirm your clients pass every server they call before enabling.

Delegations

Delegations allow users to grant agent accounts permission to act on their behalf. When a user creates a delegation to an agent account, the agent account can request OBO tokens for that user.

Key Concepts

Delegator: The user granting permission
Delegatee: The agent account receiving permission
Expiration: Delegations can have optional expiration times
Revocation: Users can revoke delegations at any time

Delegation Flow

User navigates to the agent account in the Runlayer UI
User creates a delegation to the agent account
Agent account exchanges its agent token for an OBO token scoped to the user
Agent account calls MCP tools with the user’s permissions applied

Delegations control who the agent account can act as. For OAuth-protected servers, the agent account also needs a session grant to determine whose credentials to use (see below).

Recovering from a denied OBO call

When an agent’s OBO token exchange is denied because the end-user has no active delegation (or any of the related recoverable failure reasons), the 400 invalid_grant response carries an X-Runlayer-Connect-URL header pointing at the agent account’s recovery page:

X-Runlayer-Connect-URL: https://your-runlayer-instance.com/agent-accounts/<agent-account-id>

Recommended flow:

The agent forwards the URL from the header to the end-user it is acting on behalf of.
The user opens the URL and signs in to Runlayer.
The user clicks Grant access on the agent account page. This creates the delegation and any required session grants for OAuth-protected servers in a single click.
The agent retries the OBO token exchange — it now succeeds.

The header is only set when the failure is recoverable by the end-user. Agent-side failures (disabled agent account, missing/invalid client credentials, bad agent JWT) deliberately omit the header so callers cannot probe for the existence of agent accounts they do not control.

The body of the 400 response is unchanged across all denial reasons — the recovery hint is delivered exclusively through the response header. Agents that don’t yet inspect the header continue to work; they just fall back to surfacing the raw detail message to the user.

Session Grants

Session grants control how an agent account authenticates to OAuth-protected MCP servers. A session grant shares a user’s OAuth credentials for a specific server with an agent account, independent of delegations.

Personal vs Shared

Type	Who can use it	Limit
Personal	Only the grantor’s own OBO calls use these credentials	One per (grantor, agent account, server)
Shared	Any user’s OBO calls on this agent account can fall back to these credentials	One per (agent account, server)

Switching a connection between Each user’s own account (personal grants) and Always your account (a shared grant) can be disruptive: calls that relied on the previous grant can start failing, and users without a personal grant may need to grant the agent access to the server again.

Credential Resolution

When an agent account makes an OBO call to an OAuth-protected server, Runlayer resolves credentials in this order:

Caller’s personal grant — if the OBO caller has their own session grant for this server, their OAuth credentials are used.
Shared grant fallback — if no personal grant exists, a shared session grant (from any grantor) is used.
Error — if neither exists, the call fails with a 401 error.

Lifecycle

Session grants are created when:

A user connects to an OAuth connector attached to an agent
An admin creates one through the Agent Accounts API

Revoking a delegation through the Runlayer UI does not revoke session grants, and revoking a session grant does not revoke delegations. However, disconnecting from an agent (removing your connection) revokes both your delegation and your session grants for that agent. Additionally, when an admin deactivates a user, the user can no longer obtain new OBO tokens, effectively rendering their session grants unusable — though the grants themselves are not explicitly deleted from the system.

If the grantor’s OAuth session expires, calls relying on that session grant will fail until the grantor re-authorizes the server.

Example: Slack Agent with Multiple Users

Suppose you have an agent account called “Support Bot” that needs to call a Slack MCP server on behalf of users.

Alice connects to the agent and authorizes Slack. This creates a personal session grant for Alice.
An admin promotes Alice’s grant to shared, so it can serve as a fallback for other users.
Bob connects to the agent but does not authorize Slack — he has no personal grant.
When Support Bot makes an OBO call to Slack as Alice, Runlayer uses Alice’s personal grant (her own OAuth credentials).
When Support Bot makes an OBO call to Slack as Bob, Runlayer falls back to Alice’s shared grant (since Bob has no personal grant).
If Alice later authorizes a second user Carol, and Carol creates her own personal grant, Carol’s OBO calls use her own credentials — Alice’s shared grant is not used.

Strict Mode

By default, the OBO exchange trusts the agent’s claim of which user it acts for — a user UUID or email is enough, as long as a delegation exists. Strict mode (a per-account toggle in Settings → Agent Accounts → (account) → Settings) makes the agent prove it: the user must actually sign in and consent through a login app owned by that agent account, and only the resulting id_token is accepted as the exchange subject. Enabling strict mode provisions a dedicated OAuth login client for the account (public, PKCE-only). Register your app’s redirect URIs when enabling; the login client_id is shown read-only in the account dialog. Signing in through it doubles as consent — approving creates the delegation.

What changes at the token endpoint

Rule	Behavior
Subject type	Only `urn:ietf:params:oauth:token-type:id_token`, minted by the account’s own login app. User UUID, user email, and WorkOS access-token subjects are rejected with `invalid_grant`.
`resource` required	Every exchange must name its target server(s) via RFC 8707 `resource`, else `invalid_target`. The minted `aud` is enforced at the proxy — strict mode implies resource scoping enforcement.
Session grants	Every OAuth-protected server in the token’s `aud` must be covered by an active session grant from the delegator (personal, or shared from another user). See below.
Plugins	Not supported yet. A `resource` that names a plugin is rejected with `invalid_target`, on exchange and on refresh.
Token lifetime	`expires_in` is clamped so the token never outlives the delegation or the earliest covering session grant.
`offline_access`	Allowed, but the subject must be the id_token, and every refresh rolls the delegation (see below).

Session grants at mint

For each OAuth-protected server named in resource:

Covered — the delegator has an active personal grant, or an active shared grant exists → the exchange proceeds; the earliest grant expiry clamps the token lifetime.
Uncovered, delegator has a live OAuth session with the server → a personal grant is auto-created for exactly that server at mint.
Uncovered, latest grant was revoked → invalid_target (“no active session grant for the requested resource”). Revocation sticks — no silent re-create; the user must re-grant explicitly (e.g. re-Connect on the agent-account page).
Uncovered, no OAuth session → invalid_target (“the delegator has no valid OAuth session for the requested resource”). The user must authorize the server first.

Servers that don’t use OAuth need no grant — naming them in resource is enough.

Rolling refresh

Every refresh of a strict account’s OBO refresh token revokes the delegation and creates a fresh one starting at that moment — activity keeps the consent alive; revoking the delegation kills the whole chain. The replacement window follows the account’s delegation-lifetime setting. Two consequences:

Any other refresh token bound to the old delegation dies with it: one refresh-token chain per (agent, user) is the intended shape.
Refresh never auto-creates session grants. If a covering grant was revoked since issuance, the refresh fails with invalid_target until the user re-grants.

Recipe: strict-mode OBO end to end

Step 1 — the user signs in through the account’s login app (standard OIDC authorization-code + PKCE; the consent screen creates the delegation on first approval):

# Send the user to (login client_id from the agent-account dialog):
# https://your-runlayer-instance.com/api/v1/oauth/authorize?
#   response_type=code&client_id=$LOGIN_CLIENT_ID&redirect_uri=$REDIRECT_URI
#   &scope=openid&state=...&code_challenge=...&code_challenge_method=S256

# Your redirect handler exchanges the code; the deliverable is the id_token:
LOGIN_RESPONSE=$(curl -s -X POST 'https://your-runlayer-instance.com/api/v1/oauth/token' \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=$LOGIN_CLIENT_ID" \
  --data-urlencode "redirect_uri=$REDIRECT_URI" \
  --data-urlencode "code=$CODE" \
  --data-urlencode "code_verifier=$CODE_VERIFIER")
ID_TOKEN=$(echo "$LOGIN_RESPONSE" | jq -r '.id_token')

Verifying the id_token. It is a standard OIDC ID token signed with ES256 (P-256). Verify it against the JWKS at the jwks_uri advertised by https://your-runlayer-instance.com/.well-known/oauth-authorization-server.

Step 2 — exchange the id_token for an OBO token, naming every server the token will call ($AGENT_TOKEN and $RESOURCE as in Getting an OBO Token):

TOKEN_RESPONSE=$(curl -s -X POST 'https://your-runlayer-instance.com/api/v1/oauth/token' \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "actor_token=$AGENT_TOKEN" \
  --data-urlencode "actor_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "subject_token=$ID_TOKEN" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:id_token" \
  --data-urlencode "resource=$RESOURCE")
OBO_TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.access_token')

Step 3 — call MCP tools with $OBO_TOKEN as usual. For long-running agents, add scope=offline_access plus client_id/client_secret to the exchange to also receive a refresh token (subject must still be the id_token).

Flipping strict mode on takes effect immediately for new exchanges: callers still presenting user-id/user-email/WorkOS-access-token subjects, or omitting resource, start failing at the token endpoint. Existing delegations and refresh tokens are grandfathered, but every strict refresh rolls its delegation from then on.

Connectors for agent accounts

A recurring question when wiring agents up is how to model connectors for an agent account: whether the agent account needs its own identity in your IdP, whether a single connector can authenticate both as a user and as a service, and how many connectors you end up managing. This section answers those.

The agent account is the identity

An agent account is an identity native to Runlayer. Creating one issues a client_id / client_secret (see Authentication). You do not create a matching user or service account in Okta / Entra for each agent account, and Runlayer does not provision one for you. The agent’s identity lives in Runlayer; your IdP is unchanged. What still lives upstream is the credential the connector uses to reach the SaaS (an OAuth grant or a service token) — that is a property of the connector, not of a separate IdP identity per agent.

One connector authenticates one way

A connector’s authentication method is fixed at configuration time — Auto, OAuth 2.1, Bearer Token, or None — and a single connector authenticates exactly one of those ways. There is no connector setting that accepts both OAuth and a static bearer/API-key at once. So to reach the same upstream SaaS both as a user (OAuth / on-behalf-of) and as an autonomous service (a static service credential), configure two connectors pointed at the same MCP endpoint — one OAuth 2.1 connector and one Bearer Token connector. This is the expected pattern, not a workaround.

Agent style	Connector auth method	Whose credentials	Token the agent uses
Autonomous (M2M)	Bearer Token / env-var / header API key (or an OAuth connector set to Always your account)	A service credential you supply, or the connector owner’s shared session grant	M2M token
On-behalf-of a user (OBO)	OAuth 2.1	The calling user’s own OAuth credentials, via a session grant (Each user’s own account = personal pass-through; Always your account = shared grant)	OBO token

For a Bearer Token / API-key connector, the static credential is entered in the connector’s configuration (headers or environment variables) and is field-level encrypted at rest. How you mint that upstream credential (a Jira API token, a Slack app token, a Salesforce connected-app secret, etc.) is vendor-specific and happens in the SaaS, exactly as it would without Runlayer.

Avoid connector sprawl — scope with policy, not with more connectors

You do not need one connector per agent account. A single service-credential connector can back many agent accounts; differentiate what each agent may do with per-agent-account policies (least privilege), not by cloning connectors. In practice the ceiling for one upstream service is two connectors (one OAuth, one M2M), each reused across every agent that needs that service. To scope a read-only agent against a service that also has write access, keep one connector and restrict the agent account’s policy to read tools — you do not need a separate “read-only” connector. Creating an additional connector is only warranted when you genuinely need a different auth method or a different set of static credentials for the same endpoint.

When an agent account is attached to an OAuth connector, the connector’s credential mode — Each user’s own account (each caller’s personal session grant) vs Always your account (a single shared grant) — decides whose upstream credentials the agent uses. See Session Grants → Personal vs Shared. Autonomous agents that should never borrow a user’s identity should use a dedicated Bearer Token / service-credential connector instead.

Policies

Both agent accounts and users can have policies that control what actions they can perform. When an agent account uses an OBO token, the effective permissions are the intersection of:

The agent account’s policies
The user’s policies
Any server-level policies

This ensures that an agent account acting on behalf of a user can never exceed either party’s permissions.

Identity Attributes

Agent accounts carry an optional set of identity attributes — key/value pairs (for example team: engineering) that administrators manage in the agent account’s settings dialog or via the API. Unlike user attributes, which sync from your identity provider, agent attributes are set directly by admins, and every change is recorded in the audit log. Agent and user attributes share one attribute namespace: a policy that targets an attribute (as a principal or in a condition) applies to any user or agent account carrying it. Assigning an attribute to an agent therefore immediately places it in scope of every existing policy targeting that attribute — this is the intended way to scale policies beyond per-agent lists. Attribute keys registered under Settings → Workspace → Permission Attribute Selectors appear as suggestions in the editor, but any key is allowed; the registry only drives policy-builder dropdowns and is never used for validation. Agents with no attributes are unaffected by attribute-based policies.

Best Practices

Secure your client secret

Store your agent account’s client secret securely (e.g., environment variables, secrets manager). Never commit it to version control or expose it in client-side code.

Use OBO when a person asked for the work

If a specific user requested the work, mint an OBO token for that user. The token carries both identities, so policy is the intersection of both and the audit row names both. Use M2M only when the agent acts on its own schedule under its own authority.

Handle token expiration

Access tokens are valid for 1 hour. Implement token refresh logic in your application to request new tokens before expiration.

Apply least privilege

Configure your agent account’s policies to only allow the minimum permissions required for its function. Avoid granting broad access.

Managing Agent Accounts

The lifecycle is provision, rotate, revoke, deprovision. Create the account and hand out its credentials, rotate the secret on a schedule or on suspicion, revoke a single token or all of them when something looks wrong, disable the account to reject every token on its next request, and delete it to revoke all tokens and delegations at once. Agent accounts are managed through the Runlayer UI:

Navigate to Settings → Agent Accounts
Create new agent accounts with the Add Agent Account button (admin-only)
Configure agent account settings — including Enforce server scoping — policies, and delegations
View agent account activity in the audit logs

Every agent account has an owner: the person accountable for it, shown in the account summary when you edit the account. The creator is the owner. An account that backs a Runlayer agent takes that agent’s owner and changes owner when the agent is transferred. Ownership records who is accountable for the account. Under the unified policy engine, the owner can also change the account’s name and description, disable it, and delete it. A policy can grant the same per account: edit covers the name, the description, and disabling, and delete covers deletion. Creating accounts, rotating credentials, managing connections, and changing any other setting still require the administrator capability.

All workspace members can view agent accounts, create delegations, and create session grants. Only administrators can create agent accounts, rotate credentials, manage connections, or change settings beyond the name, description, and disabling. Under the unified policy engine, the owner can also rename, disable, and delete their account, and a policy can grant those actions per account.

Credential Rotation

Agent account credentials should be rotated periodically or after security events to maintain security.

When to Rotate

Scheduled rotation: Rotate credentials every 90 days as a best practice
Security incident: Immediately rotate if credentials may have been exposed
Personnel changes: Rotate when team members with access leave the organization
Suspicious activity: Rotate if you detect unusual API usage patterns

How to Rotate

Navigate to Settings → Agent Accounts
Select the agent account to rotate
Click Rotate Credentials
Confirm the rotation
Save the new client secret immediately (shown only once)
Update your application with the new credentials

Agent accounts linked to an Agent cannot be rotated from the Agent Accounts page. The UI will direct you to the agent’s page instead, where you can rotate the credentials for the linked account.

Impact of Rotation

When you rotate credentials:

Old client secret is immediately invalidated - The agent account cannot authenticate with the old secret to obtain new tokens
Existing tokens remain valid until expiry - Previously issued JWTs (both M2M and OBO) continue to work for up to 1 hour unless you revoke them
Delegations remain intact - No need to recreate delegations
Policies are unchanged - Access rules continue to apply

After rotating credentials, existing access tokens remain valid for up to 1 hour. If you need to fully block access immediately, revoke the outstanding tokens or disable the agent account in addition to rotating credentials. Update your application with the new client secret promptly, as no new tokens can be obtained with the old secret.

Revoking Tokens

Every M2M and OBO access token Runlayer mints is registered at issuance and checked on every request, so revocation takes effect on the token’s next use — you don’t have to wait for the token to expire.

Revoke a single token

Send the token to the RFC 7009 revocation endpoint with the agent account’s client credentials:

curl -s -X POST 'https://your-runlayer-instance.com/api/v1/oauth/revoke' \
  --data-urlencode "token=$OBO_TOKEN" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET"

This works for M2M access tokens, OBO access tokens, and OBO refresh tokens — pass the token itself and Runlayer detects the type. Per RFC 7009 the endpoint always returns 200: unknown, already-revoked, or another account’s tokens are silent no-ops. A revoked access token is rejected everywhere it is accepted — proxy calls, API calls, and the RFC 8693 exchange (a revoked M2M token can no longer be exchanged for new OBO tokens). Each revocation is recorded in the audit logs.

Access and refresh tokens are revoked independently: revoking an OBO access token does not revoke the refresh token that produced it, and revoking a refresh token does not revoke access tokens already issued. Revoke each token, or disable the agent account to stop everything at once.

Revoke everything

Disable the agent account (Settings → Agent Accounts): all of its tokens stop working immediately and no new tokens can be minted. Re-enabling restores unexpired tokens.
Delete the agent account: permanently revokes all outstanding access and refresh tokens and all delegations.

Error Handling

When authenticating or making API calls, you may encounter these common errors:

Authentication Errors

Error Code	Error	Cause	Remediation
400	`unsupported_grant_type`	Wrong grant type used	Use `client_credentials` (M2M / agent token) or `urn:ietf:params:oauth:grant-type:token-exchange` (OBO)
401	`invalid_client`	Invalid client ID or secret	Verify credentials are correct and not rotated
400	`invalid_grant`	Invalid or expired token	Re-authenticate to get a new token
400	`invalid_grant`	User deactivated, not found, or no delegation	Verify the user exists, is active, and has delegated to the agent

OBO Token Exchange Errors

Error Code	Error	Cause	Remediation
400	`invalid_request`	Unsupported `subject_token_type`	Use `urn:runlayer:token-type:user-id`, `urn:runlayer:token-type:user-email`, or `urn:ietf:params:oauth:token-type:access_token` — or `urn:ietf:params:oauth:token-type:id_token` for Strict Mode accounts
400	`invalid_request`	Missing `subject_token` / `subject_token_type` on token exchange	Pass user identity as `subject_token` with a supported `subject_token_type`
400	`invalid_request`	Agent JWT placed in `subject_token` (tokens swapped)	Agent token goes in `actor_token`, user identity in `subject_token` (RFC 8693 §2.1)
400	`invalid_request`	Wrong `actor_token_type`	Must be `urn:ietf:params:oauth:token-type:access_token`
400	`invalid_grant`	User not found, inactive, no delegation, or malformed `subject_token` value (uniform denial message)	Send the user to the `X-Runlayer-Connect-URL` recovery page (see Recovering from a denied OBO call); double-check the `subject_token` value
400	`invalid_grant`	Agent account disabled	Contact admin to re-enable agent account
400	`invalid_grant`	Strict Mode account presented a user-id, user-email, or WorkOS access-token subject	Present an id_token minted by the account’s own login app
400	`invalid_target`	`resource` missing on the exchange (Strict Mode or resource scoping enforcement), or on the agent-token call (resource scoping enforcement)	Name every target server via RFC 8707 `resource` on both calls
400	`invalid_target`	The exchange named a server or plugin outside the agent token’s `aud` (Strict Mode or resource scoping enforcement)	Scope the agent token to every target the exchange requests
400	`invalid_target`	Strict Mode: an OAuth server named in `resource` has no covering session grant, or the grant was revoked	The user re-connects / re-authorizes that server — see Session grants at mint
400	`invalid_target`	Strict Mode: `resource` names a plugin	Name the servers instead; strict-mode accounts can’t scope a token to a plugin yet

Proxy Call Errors

Error Code	Error	Cause	Remediation
401	`No credentials available for this server. A session grant is required.`	No session grant exists for this agent account and server	Create a session grant by granting access on the connector
401	`OAuth authorization required. Please authorize this server first.`	Grantor’s OAuth session is missing or expired	Grantor needs to re-authorize the MCP server
403	`Access denied ...` (or a tool error `Access denied by policy: ...`)	PBAC policy blocked the request or tool call	Review agent account and user policies
Tool error	`agent_account_not_granted`	The agent account is not linked to a Runlayer agent (for example your own harness) and no admin connected it to the Runlayer connector for this agent-changing tool. The default access everyone has to Runlayer MCP does not count	An admin connects the agent account to the Runlayer connector with the tools it needs, for example `update_agent`: an allow policy on the Runlayer connector that names this agent account and has no conditions. Policies for all agent accounts, or with conditions, do not count. A grant covers the whole tool: `update_agent` can also replace connectors and skills
Tool error	`agent_scope_denied`	A Runlayer agent’s run tried to change another agent through Runlayer MCP. A run can change only its own agent unless Runlayer MCP is attached to that agent as a connector	Attach the Runlayer MCP connector to the agent that manages other agents
Tool error	`agent_scope_unresolved`	The agent account is linked to more than one Runlayer agent, so Runlayer MCP cannot tell which agent is running and blocks agent configuration changes	Contact Runlayer support

Example Error Responses

Agent account authentication and token exchange errors follow RFC 6749 §5.2: a JSON object with error and error_description fields (a legacy detail field is also emitted for backward compatibility):

{
  "error": "invalid_grant",
  "error_description": "invalid_grant: subject token exchange denied",
  "detail": "invalid_grant: subject token exchange denied"
}

When the denial can be recovered by the end-user (missing delegation, user not found / inactive, malformed actor token), the same response also carries an X-Runlayer-Connect-URL header:

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Runlayer-Connect-URL: https://your-runlayer-instance.com/agent-accounts/<agent-account-id>

{"error":"invalid_grant","error_description":"invalid_grant: subject token exchange denied","detail":"invalid_grant: subject token exchange denied"}

Check the error_description field for specific guidance on how to resolve the error. When X-Runlayer-Connect-URL is present, forward that URL to the end-user — clicking through and signing in lets them grant the missing delegation in one step. See Recovering from a denied OBO call.

​What is an Agent Account?

​Why agents need their own identity

​Identity at every layer

​Token Types

​M2M Token (Machine-to-Machine)

​OBO Token (On-Behalf-Of)

​How OBO Works

​Authentication

​Getting an M2M Token

​Getting an OBO Token

​Scoping a token to specific servers (optional)

​Calling MCP Tools

​Resource Scoping Enforcement

​Delegations

​Key Concepts

​Delegation Flow

​Recovering from a denied OBO call

​Session Grants

​Personal vs Shared

​Credential Resolution

​Lifecycle

​Example: Slack Agent with Multiple Users

​Strict Mode

​What changes at the token endpoint

​Session grants at mint

​Rolling refresh

​Recipe: strict-mode OBO end to end

​Connectors for agent accounts

​The agent account is the identity

​One connector authenticates one way

​Avoid connector sprawl — scope with policy, not with more connectors

​Policies

​Identity Attributes

​Best Practices

​Managing Agent Accounts

​Credential Rotation

​When to Rotate

​How to Rotate

​Impact of Rotation

​Revoking Tokens

​Revoke a single token

​Revoke everything

​Error Handling

​Authentication Errors

​OBO Token Exchange Errors

​Proxy Call Errors

​Example Error Responses

What is an Agent Account?

Why agents need their own identity

Identity at every layer

Token Types

M2M Token (Machine-to-Machine)

OBO Token (On-Behalf-Of)

How OBO Works

Authentication

Getting an M2M Token

Getting an OBO Token

Scoping a token to specific servers (optional)

Calling MCP Tools

Resource Scoping Enforcement

Delegations

Key Concepts

Delegation Flow

Recovering from a denied OBO call

Session Grants

Personal vs Shared

Credential Resolution

Lifecycle

Example: Slack Agent with Multiple Users

Strict Mode

What changes at the token endpoint

Session grants at mint

Rolling refresh

Recipe: strict-mode OBO end to end

Connectors for agent accounts

The agent account is the identity

One connector authenticates one way

Avoid connector sprawl — scope with policy, not with more connectors

Policies

Identity Attributes

Best Practices

Managing Agent Accounts

Credential Rotation

When to Rotate

How to Rotate

Impact of Rotation

Revoking Tokens

Revoke a single token

Revoke everything

Error Handling

Authentication Errors

OBO Token Exchange Errors

Proxy Call Errors

Example Error Responses