Manage Authorization
System_ManageAuthorization lets an agent ask a user once for all the authorization a job needs, instead of stopping them at one sign-in after another as each tool runs. This page is for agent developers and platform operators who run Gateways with tools that act as the user. It explains when the tool appears on a gateway, how an checks and requests authorization with it, and what comes back. Arcade adds the without any setup, so read this page to learn what your agents see and how to leave the tool out.
Why it exists
Each tool asks only for the permissions it needs. Two tools for the same provider often need different permissions, so authorizing one doesn’t always cover the next. An that calls one at a time can stop the at a new sign-in partway through a job, and again later.
With System_ManageAuthorization, the names every the job will use before it starts. Arcade combines what those tools need into one request per provider, so the authorizes once and the job runs without interruption.
When it appears on a gateway
Arcade adds System_ManageAuthorization to a gateway’s list when at least one tool the gateway offers the needs user authorization. It needs no setup, and it appears whether Tool Recommendation is on or off. On a gateway whose tools need no authorization, it doesn’t appear, and a call to it is refused.
Where the tool appears, Arcade also adds a short instruction before the gateway’s own instructions. It tells the to call the once, with every tool it plans to use, before it starts a job that needs authorization.
The tool exists only on Gateways. The ’s listings don’t include it.
To leave the tool out for one client, add ?arcade_tools=false to the gateway URL the client connects to. That connection gets none of the Arcade tools. On a self-hosted , engine.manageAuthorization.enabled in the Helm values turns the off for the whole deployment.
What an agent can do with it
The has two actions:
| Action | What it does |
|---|---|
status | Reports what the user has already authorized for the tools the agent names. It asks the user for nothing. |
authorize | Returns an authorization link for each provider that still needs one. |
Both actions take tools, the tools the plans to use. Name each as the agent’s tool list shows it, such as Gmail_SendEmail. Arcade also accepts the dotted form that Arcade.SelectTools returns, such as Gmail.SendEmail. Name every tool the job will reach, including steps the didn’t spell out, such as finding a channel before posting to it. Each permission asked for now is one the user doesn’t have to grant later.
Check what the user has authorized
{
"action": "status",
"tools": ["Gmail_ListEmails", "Gmail_SendEmail", "Slack_SendMessage"]
}The result has an entry for each provider those use. Each entry names the provider, the tools it covers, the permissions those tools need from it, and one of these statuses:
authorized: The user has already granted everything those need.authorization_required: The user must authorize before those can run.provider_unavailable: Arcade can’t offer authorization for this provider right now, for example because its isn’t configured. Calling again won’t produce a link.
that need no authorization get no entry. If none of the named tools need authorization, the result says so, and suggests naming the gateway’s other tools to check them.
Request authorization
{
"action": "authorize",
"tools": ["Gmail_ListEmails", "Gmail_SendEmail", "Slack_SendMessage"]
}The result has the same entries as a status check. Each provider that still needs authorization gets one link, in its entry’s authorization_url. The link asks for the combined permissions the named need from that provider. A provider the has already authorized is reported as authorized, and gets no link.
How the links usually reach the user depends on the client:
- A client that supports URL elicitation gets the links as a URL elicitation instead of the result, and asks the to open them.
- Any other client gets the links in the result, and the shows them to the .
A call that connects another profile is the exception. Every link from that call comes back in the result, whatever the client supports.
What the agent does next
Each result also carries a short summary and instructions for the ’s next step. After authorize, the instructions tell the agent to show the user every link and, once the user is done, to call the again with status and the same arguments to confirm. The tool’s description and these instructions guide the model, so most agents need no extra prompting.
A job is ready only when every provider it needs is authorized. When some are and some aren’t, the instructions tell the that the job isn’t ready, and to wait for the instead of fetching data from the providers that are ready. When the only providers left are unavailable, they tell the agent to let the user know which ones, and to carry on with whatever the job allows.
A call is refused when action is neither status nor authorize, when tools is missing, empty, or isn’t a list of tool names, or when it names a tool the gateway doesn’t offer. The refusal tells the what to fix.
don’t have to use the . A tool call that needs authorization still returns its own authorization prompt.
Choose a profile
While multi-profile support is on, users can connect more than one for some providers, and a status check reports each profile as its own entry. The then takes an optional profiles argument. Each entry names a provider and, optionally, the arcade_profile_id of one of the ’s profiles there. An entry with an ID checks or authorizes only that profile:
{
"action": "status",
"tools": ["Gmail_SendEmail"],
"profiles": [
{
"provider_id": "google",
"arcade_profile_id": "2qR8sNvYk3TmB7cXw1LpJ5fHdZe"
}
]
}With authorize, an entry with only a provider_id connects another . See Check and authorize each profile and Connect another profile for how each one works.
Last updated on