App access control for agents
This reference extends https://app.tokay.io/llms.txt with app access operations for AI agents. Change access only when the user explicitly asks or a named readiness action requires it.
Last updated
AI agent? Start with llms.txt.
The access model
- A Project is one app and one login and sign out realm.
- Each WEB or FUNCTION Service directly stores
PUBLIC,PRIVATE, orINTERNAL. - Internal has no public address, no custom domain routing, and no sign in. Only the other Services in the Project reach it, at its
internalAddress. - Public bypasses Tokay sign in and forces every request to be anonymous.
- Private admits the union of same-project Groups, exact-email People, company domains, and project Machines in that Service's audience.
- Private with no audience members admits nobody. A deployed Service remains
UP_TO_DATEand reports the advisory actionCREATE_SERVICE_ACCESS_MEMBER. - The Project setting
newServiceAccessis copied into new routable Services unlessensureServiceBundlepassesaccess. Changing it never changes existing Services. New Projects default it toPRIVATE. - A Person who creates a Private Service joins its audience as an exact-email Person, an ordinary member anyone with project write can remove. A Bot that creates one is not added, because a Bot has no email.
- Project and Workspace membership do not grant app access.
- Groups are reusable inside one Project. Each Group has a mutable name and an immutable slug used by app code.
- A Group may contain exact email People, company email domains, and Machines from the same Project. Public mailbox providers such as
gmail.comrequire an exact address. - Groups are reusable; direct Person, domain, and Machine members avoid throwaway Groups for one-off access. Groups do not contain Groups.
- Matching Groups define the Group slugs sent to that Service. Direct-only admission sends an empty Group list.
- There are no deny rules or inherited audiences.
- A Private WEB Service may add public routes, forced anonymous by HTTP method and exact path or trailing
/*prefix. - OAuth clients are Person delegations, not Group members. Independent automation uses a Machine identity.
Switching a Service to Public is nondestructive. Audience members, public routes, browser realm records, OAuth grants, Machine credentials, and Group membership stay stored. Returning to Private evaluates them against current authority.
What to call
| Intent | Tokay API | Official Tokay MCP |
|---|---|---|
| Change the default for future Services | setProjectNewServiceAccess |
mutate_platform_graphql |
| Change one Service posture | setServiceAccess |
mutate_platform_graphql |
| Create a Group | createAccessGroup |
mutate_platform_graphql |
| Rename a Group | updateAccessGroup |
mutate_platform_graphql |
| Delete an unused Group | deleteAccessGroup |
mutate_platform_graphql |
| Create one Group member | createAccessGroupMember |
mutate_platform_graphql |
| Delete one Group member by member ID | deleteAccessGroupMember |
mutate_platform_graphql |
| Remove one Person's direct memberships from a Project | deleteAppPersonAccessMembers |
mutate_platform_graphql |
| Remove a departing Workspace member's direct app access everywhere | deleteWorkspaceMemberAppAccessMembers |
mutate_platform_graphql |
| Create one Service audience member | createServiceAccessMember |
mutate_platform_graphql |
| Delete one Service audience member by member ID | deleteServiceAccessMember |
mutate_platform_graphql |
| Add a WEB public route | createServicePublicRoute |
mutate_platform_graphql |
| Remove a WEB public route | deleteServicePublicRoute |
mutate_platform_graphql |
| Create a Machine | createMachine |
mutate_platform_graphql |
| Issue a Machine credential | issueMachineCredential |
mutate_platform_graphql |
| Revoke a Machine credential | revokeMachineCredential |
mutate_platform_graphql |
| Delete a Machine and its credentials | deleteMachine |
mutate_platform_graphql |
| Rotate a project's preview link | rotateProjectPreviewLink |
mutate_platform_graphql |
| See access history | Project.accessServiceEvents, Project.accessGroupEvents |
Query through the normal read surface |
App access is part of PROJECT_WRITE. setServiceAccess, in either direction, and createServicePublicRoute change who reaches a Service, so they confirm first: the first call changes nothing and fails with CONFIRMATION_REQUIRED, carrying the impact in extensions.confirmation. Repeat the unchanged call with confirmationToken added to the input to apply it. Membership changes, Groups, public route removal, creating a Machine, and the default for future Services are ordinary mutations. Issuing or revoking a Machine credential and deleting a Machine confirm like any credential change.
Protect a Service
mutation ProtectService($service: ID!) {
setServiceAccess(input: { service: $service, access: PRIVATE }) {
service {
id
access
deployReadiness { status action reason message }
}
}
}
This change takes effect through the access authority feed. It does not run a deployment. If the audience is empty, the Service safely denies everyone and reports UP_TO_DATE with CREATE_SERVICE_ACCESS_MEMBER.
Use PUBLIC to bypass Tokay sign in for the whole Service. Public requests never receive Tokay identity, even when the caller presents a recognizable browser, OAuth, or Machine credential.
Create and populate a Group
mutation CreateGroup($project: ID!) {
createAccessGroup(input: {
project: $project
name: "Finance"
slug: "finance"
}) {
accessGroup { id name slug memberCount }
}
}
The slug must begin with a lowercase letter and contain only lowercase letters, digits, and underscores. It is immutable. Rename only the display name with updateAccessGroup.
Add one member per mutation. Set exactly one of personEmail, emailDomain, or machine.
mutation CreateGroupMember($group: ID!) {
createAccessGroupMember(input: {
accessGroup: $group
emailDomain: "acme.com"
}) {
accessGroup { id memberCount }
}
}
Exact email addition may create the workspace scoped app Person internally. Public mailbox providers may be added only as exact emails, never as domain members. Partial Person search stays limited to active People already known through that Project. A Machine must belong to the same Project as the Group.
Populate the Service audience
Create exactly one Group, Person email, domain, or Machine member per mutation.
mutation CreateServiceMember($service: ID!, $group: ID!) {
createServiceAccessMember(input: {
service: $service
accessGroup: $group
}) {
service { id access }
}
}
Creation is idempotent. A Service admits an actor when the actor matches any audience member. It sends only matching Group slugs; direct-only admission sends [].
Each Service may include at most 32 Group slugs and 384 bytes of encoded slug JSON. Tokay enforces this complete claim envelope when creating a Group member and never truncates identity claims.
Read current rows through Service.accessMembers(searchText:). Service.accessMemberCandidates(searchText:) lists the verified Workspace email domains, same-project Groups, eligible People, and live Machines that can still be added, excluding rows already in the audience. Delete Group and Service members by the stable member Node ID from these connections. Other domains and previously unseen Person emails are direct create inputs. A Group cannot be deleted while any Service uses it.
Remove a Person from one Project
deleteAppPersonAccessMembers(input: { project, appPerson }) deletes that Person's direct membership rows from every Group and Service in the named Project and returns deletedMembershipCount. It does not change another Project and does not create a hidden block. If the Person still matches a Group or direct Service domain rule, that rule still admits them.
Removing a Workspace member does not remove their app access. Before deleteWorkspaceMember, read workspace.servicesAdmittingEmail(email:) and ask the user whether to also call deleteWorkspaceMemberAppAccessMembers(input: { workspaceMember }), which deletes their direct memberships in every Project of the Workspace.
Workspace wide suspension uses the app Person principal's suspendedAt authority state. It blocks the Person across that Workspace without deleting Group membership.
Add public routes to a WEB Service
mutation PublicRoute($service: ID!, $confirmationToken: String) {
createServicePublicRoute(input: {
service: $service
methods: ["POST"]
pathPattern: "/webhooks/stripe"
confirmationToken: $confirmationToken
}) {
servicePublicRoute { id methods pathPattern }
}
}
A public route widens access, so the first call changes nothing and fails with CONFIRMATION_REQUIRED. Show the user impact.warning, then repeat the call with confirmationToken. List a Service's routes with Service.publicRoutes { nodes { id methods pathPattern } } and remove one with deleteServicePublicRoute(input: { servicePublicRoute }), which does not confirm.
An exact rule matches one proxy visible path. A trailing /* matches descendants but not the unslashed root. GET also covers HEAD. /* is invalid. FUNCTION does not support public routes.
A matching public route is always anonymous. Tokay strips browser, OAuth, and Machine credentials before proxying. Your code must still verify provider signatures or its own application credentials.
Public routes may be added while a Service is Public. They stay stored, dormant, and take effect when the Service is Private.
Machines and OAuth
Creating a Machine emits no secret. Add it directly to each intended Service or through a reusable Group, then issue an independently named credential.
mutation IssueMachineCredential($machine: ID!, $confirmationToken: String) {
issueMachineCredential(input: {
machine: $machine
label: "billing worker"
confirmationToken: $confirmationToken
}) {
machineCredentialCreation {
token
machineCredential { id label }
}
}
}
The first call changes nothing and fails with CONFIRMATION_REQUIRED. Repeat it with confirmationToken and the response carries token, the only time Tokay shows it. Store its one time value as a Secret of the Project that runs the calling software, with set_project_secret or setProjectSecretValueByName. Never echo it or commit it to source. When the caller runs outside Tokay, hand the value to the user. If the confirmed response is lost, the credential exists but nobody holds its token, so revoke it from Machine.credentials and issue another. The caller sends it as Authorization: Bearer <token>. Through Tokay MCP the same mutation runs in mutate_platform_graphql under PROJECT_WRITE.
Tokay Access OAuth acts for an admitted Person and stays bound to one Private Service and exact resource URI. It never grants admission by itself. Public makes authorization and refresh unavailable but preserves grants. Returning Private revalidates every grant against the current Service audience.
Identity and propagation
Private requests receive X-Tokay-Actor-Type, X-Tokay-Actor-Id, optional Person email and name, and complete JSON Group slugs in X-Tokay-Actor-Groups. Values are PERSON, MACHINE, or SERVICE. X-Tokay-Actor-Id is the actor's Node ID, the id the Tokay API returns for that AppPerson, Machine, or Service, so an app's allow list matches what GraphQL shows. Store and compare it as an opaque string. SERVICE marks a call from another Service in the same Project through its internalAddress: X-Tokay-Actor-Id is the calling Service's id, Groups are [], and there is no email. It reaches Public and Private Services alike, and never needs sign in. A Project is one trust domain. Its Services share Secrets, databases, and a network, so identity headers protect a Service from outside callers, not from its siblings. Put Services that should not trust each other in separate Projects. Same origin browser code can read the same Person and Groups from GET /.tokay/access/me. A Machine can call the same path with its credential to learn its own id, name, and Groups. On a Tokay Service address, the browser session works only on requests from the Service's own origin and on top level navigations. Browser code on another origin cannot call a Private Service with it. A frontend reaches its sibling Services on its own origin instead, as the next section describes. Custom domains keep standard SameSite=Lax behavior. An app that wants the stricter rule there can reject requests whose Sec-Fetch-Site header is not same-origin or none.
Every public request reaches the app through one proxy, which states the visitor's address as the only X-Forwarded-For entry and as X-Real-Ip. Configure exactly one trusted proxy hop, for example Express app.set('trust proxy', 1) or Flask ProxyFix(x_for=1), and the framework reports the visitor rather than Tokay's gateway. Behind a custom domain proxied by Cloudflare, that address is the real visitor, taken from CF-Connecting-IP and trusted only from Cloudflare's published ranges. Behind another CDN it is the CDN's edge address. One client address sending more than 2,000 requests in 10 seconds to one hostname receives 429 Too Many Requests with Retry-After: 10. That ceiling is a flood shield far above real traffic, not an app rate limit. See How public traffic reaches your app.
Active traffic refreshes access state promptly. The first request after idle attempts a refresh before deciding. During an Auth state feed outage, the standard plan may use last known authorization for at most 24 hours. Cold or older state fails closed. Verify a security change with a real request instead of waiting for worker reconciliation.
Browser calls to sibling Services
Browser code reaches a WEB sibling at /.tokay/to/<the sibling's short id> on the frontend's own host, so the call is same origin and needs no CORS. In a single-page frontend, Tokay builds that path, plus the path the code expects, into a browser variable it routed to the sibling, such as VITE_API_URL, and rebuilds the frontend when the routing changes. Server code that reads the same variable still receives the sibling's internalAddress. Tokay routes a browser variable only where the call can work: the committed value is a localhost address or absent, the sibling is a Public or Private WEB Service, a Public frontend never calls a Private sibling, and a frontend calls at most eight Private siblings. A server-rendered frontend keeps its committed value for now.
Read what each browser variable gets with service(id: $id) { browserReferences { nodes { envVarName status bakedValue message targetService { id name } } } }:
| status | Meaning |
|---|---|
WIRED |
The next build bakes bakedValue, a same-origin path to targetService. |
COMMITTED_VALUE |
The value committed in the code stays. Commit a new public value and push to change it. |
SECRET_NOT_BAKED |
The variable is routed to a Secret, which is never built into browser code. Store a publishable key as Config. |
SERVER_RENDERED |
The Service renders pages on the server, so Tokay doesn't route it yet. Keep the production address in code. |
FUNCTION_TARGET |
The sibling is a Function, whose address is a credential and is never built in. |
INTERNAL_TARGET |
The sibling is Internal, so browsers can't reach it. Make it Public or Private, or call it from server code. |
PUBLIC_FRONTEND_PRIVATE_TARGET |
The frontend is Public and the sibling Private, so its visitors can't sign in to it. |
PRIVATE_TARGET_LIMIT |
The frontend already calls eight Private siblings. Make this one Public, or call it from server code. |
UNRESOLVED |
Tokay couldn't tell which sibling the variable calls. Link it with setServiceEnvVarOverrideToService. |
A Private frontend checks its own access first. Signing in to it also admits the person to each Private sibling whose own Access admits them, with that sibling's Groups, and a Group or audience change takes effect at the session's next refresh. A Public sibling is reached anonymously. A Machine bearer is judged against the sibling, and a Tokay Access OAuth token, bound to the frontend, gets 403 with error: "insufficient_scope".
The sibling sees its own Tokay hostname as Host, the frontend's host as X-Forwarded-Host, and X-Forwarded-Prefix: /.tokay/to/<key>. Its responses render in the frontend's origin, so they carry Content-Security-Policy: sandbox and lose Clear-Site-Data and Service-Worker-Allowed. Its own Set-Cookie reaches the browser on the frontend's host. A Django API called this way with its session cookie needs the frontend's origin in CSRF_TRUSTED_ORIGINS, and with USE_X_FORWARDED_HOST the frontend's host in ALLOWED_HOSTS.
| Result | Meaning |
|---|---|
404 |
The key is not one of the frontend's siblings, or the path under it starts with /.tokay/. |
403 with error: "access_denied" |
The sibling's Access doesn't admit this person, or a Public frontend called a Private sibling. |
503 with error: "service_not_running" |
The sibling has no running version. Start it. |
503 with Retry-After: 30 |
The session's sibling admissions are being renewed. Retry. |
Repointing a variable keeps the running build's old sibling reachable until the rebuild deploys, except past eight Private siblings: then the running build's oldest baked Private sibling answers 404 until the rebuild deploys.
Previews
A project that previews each push runs its new versions in a preview before they go live (Releases and migration safety for agents). Each WEB and FUNCTION service there has its own address in project.previewLinks, which anyone who can read the project sees, read-only credentials included. The address is the link: whoever holds it opens that service in the preview as it is served live. A Public service opens with no credential. A Private one asks for Tokay Access sign-in or a Machine credential, with the live service's audience. Treat addresses as secrets, and give one only to whoever should try the preview.
- A Private preview host signs in through the workspace's Access origin, as live does, in a session of its own: a live session never opens a preview host, nor the reverse. Single sign-on reaches it, and signing out of either ends both.
- A Machine credential works on a preview host as it does live. An OAuth client's token doesn't, because its audience is the live service and Tokay accepts OAuth only on live hosts.
- Browser calls to siblings at
/.tokay/to/work as they do live, and reach the siblings in the preview. - An address lasts until someone rotates the link. While the preview is being prepared it answers
503witherror: "preview_starting"andRetry-After: 10, and while no copy is serving,404witherror: "preview_closed". Browsers get pages that say the same. Hold the address and retry it. - Every preview response carries
X-Robots-Tag: noindex, nofollowandReferrer-Policy: no-referrerover the app's own, and/robots.txtallows everything, so a crawler fetches a page and sees the noindex.
An address can still leak, and Tokay accepts that. DNS lookups and TLS carry it in plain text, so it can be discovered once used. Browsers send it as Origin on calls to allowed hosts. The page's own referrer policy or scripts, such as analytics or an error reporter, can pass it on. Chat tools fetch a pasted link to unfurl it, and your MCP transcript holds the previewLinks you read. Removing a member, Bot or token takes back no address they have.
Rotation is the remedy. rotateProjectPreviewLink(input: { project }) gives every preview host a new address. It needs PROJECT_WRITE and confirms like any dangerous mutation, so show the user that everyone holding the old link loses it, then repeat with confirmationToken. The old addresses stop answering within seconds, and connections open on them close once the workspace's queued work reaches the change. App settings that name an old host, such as OAuth redirects or CORS origins, need the new one. Read previewLinks again for the new addresses.
Common errors
| Result | Meaning | Response |
|---|---|---|
CREATE_SERVICE_ACCESS_MEMBER |
Deployment is complete but a Private Service admits nobody | Create a Group, Person, domain, or Machine member |
CONFIRM_STORAGE_PATH |
Deployment is complete but the code ships files at a storage path Tokay suggested | Keep or reject each path with awaitingConfirmation (Files and one off tasks) |
SERVICE_ACCESS_GROUP_CLAIM_BUDGET_EXCEEDED |
The Service Group-claim vocabulary is too large | Include fewer Groups or use shorter slugs |
ACCESS_GROUP_IN_USE |
A Service still references the Group | Delete its Service audience memberships before deleting it |
ACCESS_GROUP_MACHINE_PROJECT_MISMATCH |
The Machine and Group belong to different Projects | Use a Machine from the Group's Project |
401 invalid_token for OAuth |
Token expired, its grant SID changed, or the resource is wrong | Refresh when possible or authorize again |
401 invalid_token for a Machine |
The credential is malformed or revoked | Issue a new credential |
403 insufficient_scope for a Machine |
The credential is valid, but this Service doesn't allow its Machine, or the Machine belongs to another Project. error_description names the Machine and its Project |
Allow the Machine on the Service or one of its Groups, or use the right Project's Machine. Keep the credential |
| Prefix root remains protected | /x/* does not match /x |
Add a separate exact rule when both should be public |
PROJECT_WRITE_REQUIRED |
The Platform credential cannot change app access | Report the missing grant to the user |