> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.v2.rasen.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.v2.rasen.ai/_mcp/server.

# Resource keys

Agents, MCP servers, Knowledge sources and secrets accept an optional `resource_key` when you create
them. It lets a setup script find its own configuration again on the next run.

* Syntax: `^[A-Za-z0-9][A-Za-z0-9._:~-]{0,127}$`. A UUID is valid.

* It is set at creation only. A different key on a later update answers `409 conflict` with
  `details.reason: resource_key_immutable`; leaving it out of a `PUT` keeps the stored key.

* It is unique per resource type within the workspace. A duplicate create answers
  `409 resource_key_conflict`, and `details.existing_id` names the resource that already has it.

* Archiving does not free a key. A key is freed only when its resource is erased, destroyed or
  permanently deleted.

* An MCP server disabled through the API or app keeps its key. Creating a server with that key answers
  `409 resource_key_conflict`, naming a server the API no longer shows.

* Tools have no resource key: a tool's name is its key within the agent's draft. Calls have none.

## Find your configuration again

List operations take a repeated `resource_key` filter:

```bash
curl -sS "$RASEN_API_BASE/agents?resource_key=support-line" -H "Authorization: Bearer $RASEN_API_KEY"
curl -sS "$RASEN_API_BASE/secrets?resource_key=crm-prod" -H "Authorization: Bearer $RASEN_API_KEY"
```

A `resource_key` lookup of agents also finds an archived agent.

A typical setup script looks the key up first, and creates the resource only when the lookup is
empty. If a create answers `409 resource_key_conflict`, read `details.existing_id` and reconcile.

## Not an idempotency key

A resource key names configuration across runs. An `Idempotency-Key` protects one request against a
lost answer. Use both: a resource key to find your agent, and a new idempotency key for each create
or edit. See [Idempotency and replay](/concepts/idempotency).