Agent Accounts - Runlayer

Agent Accounts in Runlayer represent AI applications or services that interact with MCP servers on behalf of users or autonomously. They are the primary way to programmatically connect your AI applications to the Runlayer platform.

What is an Agent Account?

An Agent Account is a registered client application that can:

Authenticate programmatically using OAuth 2.0 client credentials
Call MCP tools through the Runlayer proxy
Act on behalf of users when delegated permissions
Operate autonomously with its own policies

Each agent account receives a unique Client ID and Client Secret upon creation, which are used to authenticate API requests.

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.

Agent account operates independently
Only agent account-level policies are enforced
Ideal for background jobs, scheduled tasks, or autonomous AI agents

OBO Token (On-Behalf-Of)

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

Agent account operates in the context of a delegating user
Intersection of agent account and user policies are enforced
Requires an active delegation from the user to the agent account
Ideal for user-facing AI assistants or copilots

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.

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")

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

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

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.

# 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")
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")

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")

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")

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, plus 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.

The aud claim is narrowed to the servers the principal can access. Whether the proxy enforces it is controlled per agent account by the Enforce token resource scoping setting — see Resource Scoping 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 in the token’s aud claim. Whether the proxy enforces that scope is a per–agent-account setting, Enforce token resource scoping, in Settings → Agent Accounts → (account) → Settings. When enforcement is on, the proxy rejects an aud-bearing token used against a server outside its aud with 403 invalid_target. This confines a leaked or over-shared token to exactly the servers 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 (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.
Aggregate endpoints reject scoped tokens. The agent-account aggregate MCP, plugin, and skill endpoints fan out beyond a single named server, 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 Connect 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 Dynamic (personal grants) and Owner (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.
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:

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=https://your-runlayer-instance.com/api/v1/proxy/3f6a2b1e-8c4d-4e5f-9a7b-2c1d0e9f8a7b/mcp")
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 a Runlayer-native OAuth 2.0 client — 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 Owner)	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 (Dynamic = personal pass-through; Owner = 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 — Dynamic (each caller’s personal session grant) vs Owner (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 tokens when appropriate

If your agent account is acting on behalf of a specific user, always use OBO tokens rather than M2M tokens. This ensures proper audit trails and policy enforcement.

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

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 token resource scoping — policies, and delegations
View agent account activity in the audit logs

All workspace members can view agent accounts, create delegations, and create session grants. Only administrators can create, edit, or delete agent accounts and rotate credentials.

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)	Name every target server via RFC 8707 `resource`
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

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

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?

​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?

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