Loading Gatelion
GatelionDocs
Open the console

Agents and tokens

Every agent your organization runs is registered in the console. The record says whom the agent may act for and how fast it may call. Its tokens let it connect to a Gateway. You manage agents under Tools & agents → Agents.

This page is about your own agents. Your customers' agents register themselves and are managed under Customer access; see Your customers' agents.

Create an agent

  1. Open Tools & agents → Agents and click Create agent.
  2. Give it a name, like purchasing-agent. Names are unique in the environment.
  3. Under May act for, tick the people the agent may work for. Choose at least one. People whose access was removed aren't listed.
  4. Set Calls per minute if the default of 60 doesn't fit.
  5. Click Create agent.

Agents belong to the environment selected in the console. An agent in one environment can't use another environment's Gateways or tools.

The owner

You become the agent's owner. The owner is shown on the agent's card ("owned by …") and can never approve the agent's requests. This is part of separation of duties: the person who set up an agent shouldn't also be the one who lets it act. See Approvals.

If the owner's access is removed, the agent moves to the admin who removed their access, and the tokens the owner issued stop working. See When someone leaves.

May act for

Every call an agent makes is on behalf of one person, named in the call. The Gateway refuses the call (on_behalf_of_not_allowed) unless:

  • that person is in the agent's May act for list, and
  • they've accepted their invitation and are an active member.

The person an agent acts for can't approve that call either. So for a purchasing agent that acts for Maria, approvals have to come from someone else with the Approver role.

To change the list later, click Edit on the agent's card, tick the people, and click Save. Gateways apply the change at their next sync, within about 15 seconds. People whose access was removed can't be chosen.

Issue a token

  1. On the agent's card, click Issue token.
  2. Set Valid for (days): from 1 to 365. The default is 90.
  3. Click Issue token, then copy the token at once.

The token starts with agt_ and is shown once. Gatelion keeps only a fingerprint of it, so nobody can show it to you again. If it's lost, issue a new one and revoke the old one.

Gateways accept a new token after their next sync, normally within about 15 seconds. The card lists each token by its first characters (agt_…) and when it expires, or when it was revoked.

Whoever issues a token can't approve the requests the agent makes with it.

Revoke a token

Click Revoke next to the token, then Revoke token to confirm. Gateways reject it after their next sync, normally within about 15 seconds. A revoked token can't be used again.

Revoke a token when it may have leaked, when the developer who had it leaves, or when you've replaced it. To rotate without downtime, issue the new token first, switch the agent over, then revoke the old one.

An expired token stops working on its own. Issue a new one before it expires.

Stop an agent

The switch on the agent's card stops or starts the whole agent. Turning it off asks you to confirm with Stop agent. When it's off:

  • Gateways reject every token of that agent after their next sync.
  • Its requests that are waiting for approval, or approved but not yet running, are cancelled at once. They show as Cancelled in Approvals, with the code agent_disabled. Turning the agent on again doesn't bring them back; it has to ask again.

Turn the switch on again to let the agent back in with its existing tokens.

Rate limit

Calls per minute caps how many tool calls the agent can make in each one-minute window: 60 by default, from 1 to 10,000. Each tool also has its own limit of 60 calls a minute per agent. Calls over a limit are refused as rate_limited, and the agent can retry in the next minute.

The limit is counted on each Gateway separately.

What to give the developer

To connect an agent, its developer needs three things:

WhatWhere to find it
The MCP addressFor a hosted Gateway, on its row on the Gateways page. For a Gateway in your network, http://<that machine>:5200/mcp, or the HTTPS address you set up.
The tokenFrom Issue token. Send it the way you'd send a password.
The user id of each person the agent acts forThe User id column under Tools & agents → People. The agent sends it in the X-Gatelion-On-Behalf-Of header.

The agent sends the token as a bearer token:

HTTP
Authorization: Bearer agt_…
X-Gatelion-On-Behalf-Of: <user id>

Agent tokens work only on Gateways for your own agents. A hosted Gateway set up for your customers' agents refuses them.

Send the developer to Connect an MCP client for the rest.

Related: People and invitations · Write a policy · Connect an MCP client

Still stuck? Contact support from the console.