Agent Accounts

​

What is an Agent Account?

• 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

​

Token Types

​

M2M Token (Machine-to-Machine)

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

• 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

​

Authentication

​

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

1. A user UUID from an active delegation (simplified flow)
2. A WorkOS user access token (RFC 8693 compliant)

# Get OBO token (agent acting on behalf of a user)

# Option 1: Simplified with user UUID (recommended if you have delegation)
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=client_credentials" \
  --data-urlencode "client_id=your-client-id" \
  --data-urlencode "client_secret=your-client-secret" \
  --data-urlencode "actor_token=$USER_ID" \
  --data-urlencode "actor_token_type=urn:runlayer:token-type:user-id")

# Option 2: With WorkOS user access token (RFC 8693 compliant)
# 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=client_credentials" \
#   --data-urlencode "client_id=your-client-id" \
#   --data-urlencode "client_secret=your-client-secret" \
#   --data-urlencode "actor_token=$USER_ACCESS_TOKEN" \
#   --data-urlencode "actor_token_type=urn:ietf:params:oauth:token-type:access_token")

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

echo "OBO Token: ${OBO_TOKEN:0:50}..."
# Agent now acts with intersection of agent + user policies

​

Calling MCP Tools

# 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/servers/your-server-id/tools" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "get_context",
    "arguments": {
      "query": "project structure"
    }
  }'

​

Delegations

​

Key Concepts

• Delegator: The user granting permission
• Delegatee: The agent account receiving permission
• Server Sessions: Which MCP servers the agent account can access on behalf of the user
• Expiration: Delegations can have optional expiration times
• Revocation: Users can revoke delegations at any time

​

Delegation Flow

1. User navigates to the agent account in the Runlayer UI
2. User creates a delegation, selecting which server sessions to include
3. Agent account requests an OBO token using the user’s ID
4. Agent account calls MCP tools with the user’s permissions applied

​

Server Session Configuration

1. When creating a delegation, you configure each MCP server the agent account can access
2. For OAuth-enabled servers, select the user’s existing OAuth session
3. For servers without authentication requirements, mark as “No auth required”
4. At runtime, Runlayer resolves the appropriate credentials based on this configuration

​

Policies

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

​

Best Practices

​

Managing Agent Accounts

1. Navigate to Admin → Agent Accounts
2. Create new agent accounts with the Add Agent Account button
3. Configure agent account settings, policies, and delegations
4. View agent account activity in the audit logs

​

Credential Rotation

​

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

1. Navigate to Admin → Agent Accounts
2. Select the agent account to rotate
3. Click Rotate Credentials
4. Confirm the rotation
5. Save the new client secret immediately (shown only once)
6. Update your application with the new credentials

​

Impact of Rotation

• Old credentials are immediately invalidated - Existing tokens stop working
• Active sessions are terminated - The agent account must re-authenticate
• Delegations remain intact - No need to recreate delegations
• Policies are unchanged - Access rules continue to apply

​

Error Handling

​

Authentication Errors

​

OBO Token Exchange Errors

​

Proxy Call Errors

​

Example Error Response

{
  "error": "invalid_grant",
  "error_description": "No valid delegation found for agent account 'My Agent' and user '[email protected]'",
}