# Recognition by websites

How a website can tell that a request comes from one of your agents, what it can look up about that agent, and the two switches and the key you control. What recognition is and what it costs is on [Services](/services).

## Before you start

There is nothing to set up. An agent with an account has a signing key from the first time it is needed, and STACK signs the requests the agent makes through the proxy and its cloud browser. A request that cannot be signed still goes out, unsigned.

## What a website sees

- Each signed request carries a signature that is valid for five minutes, and the address of the list of public keys.
- In the browser, page loads and requests to the page's own site are signed. Requests to other sites, such as scripts and images, are not.
- With the key id from the signature, the site can look the agent up.

## Look an agent up

```bash
curl "https://api.getstack.run/v1/agent-identity?key_id=<key id from the signature>"
```

The lookup is public and needs no sign-in. It answers by key id, by the agent's website or by its agent id, with a signed statement that says:

- the agent's id and whether it is active, suspended or closed,
- the agent's name, only if you chose to show it,
- whether its owner is verified and in good standing.

It never says who the owner is, and never why an agent is suspended. From code, `stack.agentIdentity.verified({ keyId })` looks an agent up and checks the statement's signature. From the terminal: `agent-identity lookup --key-id <id>`. The tool is `stack_lookup_agent_identity`.

## The two switches

```bash
# Show the agent's name in the lookup. It is hidden by default.
npx @getstackrun/cli account identity acct_123 show-name

# Turn the lookup off for this agent. It is on by default.
npx @getstackrun/cli account identity acct_123 off
```

Only the owner or an admin changes them. The tools are `stack_get_account_identity` and `stack_set_account_identity`. From code: `stack.accounts.identity.update('acct_123', { show_name: true })`. With the lookup off, the agent answers like one that does not exist.

## Replace the signing key

```bash
npx @getstackrun/cli account signing-keys acct_123 rotate
```

- The new key signs from then on. The old key stays published for 48 hours, so requests already signed still check out.
- Only the owner or an admin can rotate. An agent cannot, so it cannot shake off a site's ban on its key.
- stack_list_account_signing_keys lists the keys. stack_rotate_account_signing_key rotates.

A closed account stops publishing its keys at once.

## What counts as an action

Nothing here is an action. Signing, the lookup, the switches and rotating are free. A change to a switch and a rotation are written to the record.

## When it is refused

- 404 AGENT_IDENTITY_NOT_FOUND - one fixed answer for an agent that does not exist, is closed, is still opening, or has the lookup off.
- 400 AGENT_IDENTITY_LOOKUP_INVALID - give exactly one of key_id, site or agent_id.
- 429 - the lookup allows 60 requests a minute from one address.
- 403 FORBIDDEN - an agent tried to rotate the key or change a switch.

## Reference

A service that wants to check a full Passport, not only a signature, starts at [Accept agents](/accept-agents). Every tool is in the [tool reference](/docs/mcp-tools).
