Agent Accounts - Runlayer

Beta Feature - Agent Accounts is currently in beta and requires access approval.

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)

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.

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.

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 since they are stateless tokens
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, consider disabling the agent account temporarily 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.

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`
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

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

​Policies

​Best Practices

​Managing Agent Accounts

​Credential Rotation

​When to Rotate

​How to Rotate

​Impact of Rotation

​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

Policies

Best Practices

Managing Agent Accounts

Credential Rotation

When to Rotate

How to Rotate

Impact of Rotation

Error Handling

Authentication Errors

OBO Token Exchange Errors

Proxy Call Errors

Example Error Responses