> For the complete documentation index, see [llms.txt](https://docs.securepass.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.securepass.me/documentation/admin-user-guide/agentic-identity.md).

# Agentic identity

A person signs in with a username and a password. Software that acts on its own — a script, a workload, an AI agent calling a service on your behalf — needs an identity too, and the usual answer is a shared API key pasted into a config file. That key has no owner, no expiry and no record of what it did.

Agentic Identity replaces it. Each piece of software gets its own verifiable identity, a defined set of things it may do, a credential that expires, and the ability to hand a narrower slice of its permissions to something acting under it.

**Console:** Admin Console → **Agentic Identity**

![The Agentic Identity section, with Services & Policies and Agents.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/29Je9Y5qQQa1GFyUECxB/assets/01.png)

## The two halves

The section has two pages, and the distinction between them is the thing to get right before anything else.

| Page                    | What you register there                                                                                                            |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Services & Policies** | The thing being *protected* — an application or capability an agent might act against, and the named permissions that exist for it |
| **Agents**              | The thing doing the *acting* — the software identity itself, and which services it may use                                         |

So you define the service first, because an agent has nothing to be assigned to until one exists.

## Services & Policies

An **Agentic Service** is a capability agents act against — an invoice system, a certificate authority — together with its trust settings, how long its credentials last, and the named policies that describe what can be done with it.

![The Agentic Services list.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/T0ajGIU4jikCK7VgE3uI/assets/02.png)

| Column                   | Shows                                           |
| ------------------------ | ----------------------------------------------- |
| Agentic Service Name     | The service                                     |
| Trust Domain             | The SPIFFE trust domain its agents belong to    |
| Auth Type                | How agents present their identity — SVID or JWT |
| Created By / Modified By | Who, and when                                   |
| Status                   | Active or not                                   |
| Action                   | Edit and delete                                 |

### Adding a service

Select **Add Agentic Service**.

![The Add Agentic Service form.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/wkZBtTq6iPVGM6pxiHzq/assets/03.png)

| Field                 | What to enter                                                                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agentic Service Name  | A name for the capability being protected                                                                                                                               |
| Description           | What it is for                                                                                                                                                          |
| Authentication Type   | **SVID (X.509-SVID / mTLS)** or **JWT (JWT-SVID)** — how agents under this service present their SPIFFE identity, as a certificate over mutual TLS or as a signed token |
| Trust Domain          | The SPIFFE trust domain agents under this service belong to                                                                                                             |
| Default TTL (minutes) | How long an issued credential normally lasts                                                                                                                            |
| Max TTL (minutes)     | The ceiling. No agent assigned to this service can be given a longer one                                                                                                |

**TTL** is *time to live* — the lifetime of the credential an agent is issued, in minutes. When it expires the agent has to obtain a new one. It is the main reason an agent identity is safer than a shared API key: a key that leaks is useful until somebody notices, while a credential with a sixty-minute TTL is useful for at most an hour. Set the shortest lifetime the work actually needs.

### Defining policies

A **policy** is a named group of permissions. Select **+ Add Policy**.

![Adding a policy to the service.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/piEp2qyIonepwigTxBqp/assets/04.png)

Give the policy a name that says what it covers — *Invoice System*, *CA Management* — then type each permission and select **+ Add**. Each one appears as a tag beneath the field, and **Switch to JSON** lets you write the whole policy directly instead.

![The policy's permissions, ready to add.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/75I2fk22vqYpneV0cFAT/assets/05.png)

Select **Add** to put the policy into the service's list, then **Save** to save the service and its policies together.

Policies are what an agent's access is later built from, so name the permissions the way you would want to read them back in an audit log — `read:invoices` says what happened; `perm1` does not.

### Managing a service

![The saved services.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/2OwHDnnWLosyB2QBTybu/assets/06.png)

![The edit and delete actions.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/TuZYtm17LkDRx5jfq1hb/assets/07.png)

Select the pencil icon to edit the service, its TTLs and its policies.

![Editing an Agentic Service.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/iEjj1EZGFnmCFCj9Vhtt/assets/08.png)

The bin icon deletes it, with a warning that matters:

![Deleting an Agentic Service.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/CQcC3ENyt8IFPVRKhpOa/assets/09.png)

> **Caution** Deleting an Agentic Service takes every agent and sub-agent assigned to it with it — they lose access immediately. If the aim is to stop it temporarily, switch its status off instead.

## Agents

With the service defined, **Agents** is where you register the software that will use it and decide how much of the service it gets.

![The Agents list.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/cqjKnBzsJ4ZKwqXi2gkS/assets/10.png)

| Column            | Shows                                   |
| ----------------- | --------------------------------------- |
| Agent Name        | The agent, with its agent ID beneath    |
| Type              | **Main Agent** or a sub-agent           |
| Parent Agent      | The agent it was delegated from, or N/A |
| Assigned Services | Which services it may act against       |
| Status            | Active or not                           |
| Action            | Edit and delete                         |

### Adding an agent

Select **Add Agent**.

![The Agent Identity section of the Add Agent form.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/yLWT36bmFkvGcNwK7XKU/assets/11.png)

| Field                           | What to enter                                                                                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Agent Name                      | A readable name, for your benefit                                                                                                                |
| Agent ID                        | The identifier used to build the agent's SPIFFE ID. Letters, digits, dots, dashes and underscores only, no spaces, and unique across every agent |
| Purpose                         | What this agent is for                                                                                                                           |
| Max Sub-Agents                  | How many delegated identities it may create                                                                                                      |
| Allow Sub-Agent Delegation      | Whether it may delegate at all                                                                                                                   |
| Cascade Revoke on Parent Revoke | Whether revoking this agent also revokes everything below it                                                                                     |

Leave **Cascade Revoke** on unless you have a specific reason not to. Without it, revoking a compromised agent leaves its sub-agents still working.

### Assigning services

Tick each service the agent may act against, then choose how much of it.

![Full access to a service.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/2a9ENlKsb5FixBsTsPwh/assets/12.png)

**Full Access** gives the agent every policy and permission currently defined for that service — including any added later, which is the part worth thinking about.

![Custom access, with individual permissions.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/BGHp1XNjL75BdBajW5m6/assets/13.png)

**Custom Access** opens the service's policies so you can tick individual permissions — `read:invoices` without `write:invoices` or `delete:invoices`.

Each assignment carries its own **TTL in minutes**, capped at the service's Max TTL.

Prefer Custom Access. An agent that only reads cannot be made to delete, however the software calling it is manipulated.

### Sub-agents

A **sub-agent** is a narrower identity acting under a main agent — useful when one agent orchestrates several pieces of work that each need less than the whole.

![Adding a sub-agent.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/QhUYPF38p1VfyTqOUrQj/assets/14.png)

Give it a name, its own unique **Sub-Agent ID**, and a purpose, then assign its services. Each sub-agent gets its own service assignments, independent of the parent's: the main agent might hold full access while a sub-agent holds a single permission.

Select **Add**, then **Save** to save the agent and its sub-agents together.

### Managing an agent

![The agent list actions.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/2jr7cu63SZxsXDZOc4LX/assets/15.png)

The pencil icon reopens the agent.

![Editing an agent.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/OBP1EMkJWe3PL7rpzk77/assets/16.png)

The bin icon deletes it.

![Deleting an agent.](https://content.gitbook.com/content/W2srIAMN6RKFwvuEorV5/blobs/Ni5PFkPsWDGCRfu1hmoA/assets/17.png)

> **Caution** A deleted agent loses access to every service it was assigned to, immediately and everywhere.

## Putting it together

The order is always the same, and each step depends on the one before it.

1. **Define the Agentic Service** — the thing being protected, its trust domain, its auth type and its TTLs.
2. **Define its policies** — the named permissions that exist for it.
3. **Register the agent** — its identity, and whether it may delegate.
4. **Assign services to the agent** — full or custom access, with a TTL.
5. **Add sub-agents** where one agent needs to hand a narrower slice of its work to another.

Two settings are worth checking twice on every agent you create: the **TTL**, because a long one undoes most of the benefit, and **Custom Access**, because Full Access quietly grows every time someone adds a policy to the service.