Skip to main content

​
What scopes are

Scopes are strings declared at registration that describe what an agent is authorized to do. They’re embedded in the token and returned by the verify endpoint. ImaRobot does not enforce scopes — that’s the receiver’s job. ImaRobot makes the scopes visible and verifiable.

​
Format

Scopes are free-form strings. We recommend the action:resource convention: 
["read:portfolio", "read:transactions", "write:orders"]
But any string is valid — use whatever makes sense for your domain.

​
How receivers use scopes

const result = await verifier.verify(token);

if (!result.valid) {
  return res.status(401).json({ error: result.error });
}

if (!result.scopes.includes('read:accounts')) {
  return res.status(403).json({ error: 'FORBIDDEN' });
}

// Proceed with request

​
Scope examples by domain

DomainExample scopes
Financial dataread:portfolio, read:transactions, write:orders
Infrastructuredeploy:production, read:logs, manage:dns
Customer dataread:profile, write:preferences
Internal toolsread:reports, submit:expense, approve:pr

​
Scope changes

Scopes are fixed at registration. To change an agent’s scopes, revoke it and register a new agent with the updated scope list.