Scopes
The four scopes of iyedy tokens, the routes and MCP tools each one opens, and how scopes and roles combine on every request.
On this page
| Scope | Opens | MCP | Role it needs to act |
|---|---|---|---|
cartouche.read |
reading diagrams, views, versions, search, checks | yes | viewer |
cartouche.graph |
impact, dependents, dependencies, element search across diagrams | yes | viewer |
cartouche.propose |
previews and proposals | yes | contributor |
cartouche.write |
replacing a diagram's definition | never | contributor |
Every token, whatever its scopes, can call GET /v1/token.
How a request is checked
On every request with a token, in this order:
- The token. Missing, malformed, expired, revoked, outside the allowed addresses, or blocked by the organisation's policy:
401 unauthenticated, with the reason. - The place. A path that names another organisation, another account or, for a token bound to one workspace, another workspace:
404 not_found, the same answer as for an id that does not exist. - The route. A route outside the public API:
403 permission_denied, reasontoken_not_accepted. A token never creates tokens, administers, opens the live connection, runs the Assistant or exports a library. - The scope. A missing scope:
403 permission_denied, reasoninsufficient_scope, with the scope inrequired. - The role. The route then checks your role, or the service account's, like for anyone: restricted diagrams, shares, trash, legal holds and locks apply.
cartouche.read
Reads the workspace and its diagrams.
Route (under /v1/t/{tenantId}/w/{workspaceId}) |
What it does |
|---|---|
GET /me |
you in this workspace: role, limits, what you may do |
GET /diagrams, GET /diagrams/{did} |
the diagrams you can read, one diagram's summary |
GET /diagrams/{did}/versions |
saved versions |
GET /diagrams/{did}/layouts |
the layouts of the views |
GET /diagrams/{did}/source |
the diagram's definition as text |
GET /diagrams/{did}/views, GET /diagrams/{did}/views/{view} |
the views, and one view in a format |
GET /search |
search over names and contents |
POST /checks |
validation and architecture checks; nothing is stored |
POST /tools/{tool} |
one of the reading tools the MCP server shares |
It also opens the organisation's MCP endpoint, POST /v1/t/{tenantId}/mcp, when the organisation allows MCP clients.
cartouche.graph
Follows relationships across the diagrams you can read.
Route (under /v1/t/{tenantId}/w/{workspaceId}) |
What it does |
|---|---|
GET /graph/impact |
what depends on an element, transitively |
GET /graph/dependents |
what uses it directly |
GET /graph/dependencies |
what it depends on |
GET /graph/search |
elements by meaning or name, with their neighbours |
cartouche.propose
Prepares changes that a person reviews. With the viewer role it previews nothing and stores nothing.
Route (under /v1/t/{tenantId}/w/{workspaceId}) |
What it does |
|---|---|
POST /diagrams/{did}/preview |
what a change would do; nothing is stored |
POST /diagrams/{did}/proposals |
stores a proposal |
GET /diagrams/{did}/proposals, GET /diagrams/{did}/proposals/{pid} |
the proposals and one proposal |
POST /diagrams/{did}/proposals/{pid}/withdraw |
takes back one of your open proposals |
Deciding on a proposal is never open to a token: a person applies or rejects it in the app. See Propose a change through the API.
cartouche.write
Route (under /v1/t/{tenantId}/w/{workspaceId}) |
What it does |
|---|---|
PUT /diagrams/{did}/source |
saves a new definition of the diagram, as a new version in its history |
The new definition is checked first: an invalid one is refused and nothing is saved. Over MCP, this scope is never honoured: Claude and MCP clients propose, they never write.
On the access page
When Claude signs in, the three MCP scopes appear on the access page in plain words: see Sign-in, permissions and disconnecting.
Was this page helpful?Your answer is anonymous and counts only if you accepted measurement.
What went wrong?
Don't write personal data.