Skip to content
Markdown
GuideForOwnerWith Foxden Admin

Give an agent its own identity ​

This page lets an Owner set up an AI agent that works on its own (on a server, in a scheduled job) under its own name, with a key of its own instead of a person's. Everything the agent does is shown in the apps under its name, and you can cut it off at any time without touching anyone's account.

An agent is an identity in Foxden Admin that can never sign in. It has a name, an address, and an Owner: the person answerable for it. It reaches the apps it is granted, as itself, through the AI gateway.

Before you start ​

  • You are an Owner in Admin.
  • Choose an address for the agent on a domain nobody signs in with. Admin suggests one such as fox@agents.example.com. An address on your company's sign-in domain is refused, because a real account could then sign in as the agent.

Create the agent ​

  1. In Admin, open Workspace › People.
  2. Select Add agent.
  3. Fill in Name (what the apps show beside everything it does), Email and Owner (an active person in your company).
  4. Select Create agent.

The agent appears in the People table with an Agent label.

Give it access to apps ​

  1. In the People table, open the agent's record.
  2. Under Access, give it the apps it needs.

An agent can use an app; it is never given more, and it is never given access to Admin. It can be granted Fennec, Arctic, Corsac, Pampas, Culpeo, Cape and Library. Each app creates the agent's account there when you grant it.

Give it a key ​

An agent connects in one of two ways. Both are on the agent's own page: in its record, under Keys, select Manage its keys.

A long-lived key ​

  1. Under Suite keys, enter a Label that says where it runs ("agent box").
  2. Choose Expires: Default lifetime, 30 days, 90 days, 1 year or Never (until revoked). The default lifetime is set on the server (90 days unless the operator changed it).
  3. Select Mint key. The key is shown once. Copy it now: only its hash is stored.

The agent's MCP client calls the gateway's address (https://<your Admin address>/api/suite/mcp) with the header Authorization: Bearer <key>. A key cannot be minted until the agent has access to at least one app.

A client that signs in on its own ​

Use this when no long-lived key should sit on the agent's machine.

  1. Under Unattended sign-in, select Create client. A client id and a secret are shown once.

  2. The agent exchanges them for a token that expires within the hour (by default):

    bash
    curl -s https://admin.example.com/api/oauth/token \
      -u "$CLIENT_ID:$CLIENT_SECRET" \
      -d grant_type=client_credentials

    The answer holds access_token, expires_in and scope: "suite". The client id and secret can also go in the form body as client_id and client_secret.

  3. The agent sends Authorization: Bearer <access_token> to the gateway, and asks for a new token when it expires.

Creating a second client lets you change the secret without a gap: switch the agent over, then remove the first.

What the agent can reach ​

Exactly the apps it is granted, at the level Can use, as itself. Each app applies that level to the agent as it would to a person. The Owner's rules on Assistant rules apply to it like to any connection, and whether it must confirm destructive calls follows the company's setting.

Corsac can also give an agent a key for its own API: someone who can manage Corsac does it under API keys, Keys for agents. See Use the Corsac API.

Cut an agent off ​

  • Revoke one key. On the agent's page, under Suite keys, open the key's actions and select Revoke. The agent is refused on its next call with it.
  • Remove a client. Under Unattended sign-in, select Remove. Its secret stops working at once; tokens it already issued expire on their own within the hour.
  • Stop the agent everywhere. In its People record, suspend it. Suspending it, or revoking a key, cuts it off on its next call.
  • Pause it in one app only. Use Workspace › Assistants › Rules.

New agent keys and clients are recorded in Workspace › Activity.

Troubleshooting ​

Creating the agent says the domain is one this console admits by sign-in ​

The address is on a domain people sign in with. Use an address on another domain, such as the one Admin suggests.

The agent gets 401 from the gateway ​

The key was revoked or has expired, the client's token has expired, or the agent is suspended. The gateway gives no reason. Mint a new key or ask for a new token.

An app is missing for the agent ​

The agent was not granted that app, or the app has not created the agent's account. Open the agent's record and check its access. The agent can call foxden_status to see each missing app and why.

Foxden is open source under Apache-2.0.