> For the complete documentation index, see [llms.txt](https://docs.inrupt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.inrupt.com/ess/3.0/services/identifiers.md).

# Identifiers

{% hint style="success" %}
Added in version 3.0.0
{% endhint %}

ESS assigns identifiers to storages, resources, agents, and clients. These identifiers are permanent and globally unique. They remain constant regardless of infrastructure changes such as a deployment domain migration or subdomain rename.

## Identifier Types

ESS assigns identifiers to the following entity types:

| Entity       | Description                                                      | Example                         |
| ------------ | ---------------------------------------------------------------- | ------------------------------- |
| **Storage**  | A user's Pod                                                     | Assigned at provisioning time   |
| **Resource** | Any resource within a storage (files, containers, RDF resources) | Assigned at creation time       |
| **Agent**    | A user or entity identified by a WebID                           | Mapped from IdP identity        |
| **Client**   | An application identified by a Client ID                         | Mapped from client registration |

Identifiers are automatically assigned at creation time and remain constant for the lifetime of the entity.

## Canonical URIs

ESS exposes two URI schemes for accessing resources:

### Canonical URIs

```none
https://storage.{ESS Domain}/{storage-id}/sc/{resource-id}
```

Canonical URIs identify both the storage and the resource. They are:

* **Permanent**: Never change, even if the deployment domain changes
* **Opaque**: Do not reveal path information or user-identifiable data
* **Safe**: Mitigate PII leakage in logs, audit trails, and external references

{% hint style="warning" %}
**Treat canonical URIs as opaque**

Clients must not parse a canonical URI, extract its component parts, or depend on the structure shown above. The layout of the URI is an internal detail and may change. Store and pass canonical URIs whole, and use the [bidirectional mapping](#bidirectional-mapping) to resolve them.
{% endhint %}

### Path-Based URIs

```none
https://storage.{ESS Domain}/{storage-id}/sp/{resource-path}
```

Path-based URIs use the human-readable resource path. They continue to work for backward compatibility, but because they embed both the deployment domain and the resource path, they are not durable references.

{% hint style="warning" %}
**Important**

Access Grant issuing and Notification subscriptions **must** use canonical resource URIs (the `/sc/` form). This ensures that grants and subscriptions remain valid even if the deployment domain changes.
{% endhint %}

## Bidirectional Mapping

ESS maintains a bidirectional mapping between identifiers and resolvable addresses. Given an identifier, you can resolve the current address; given a current address, you can discover the identifier.

This mapping is managed internally by ESS and is available through standard HTTP content negotiation on resource responses.

## Tombstoning

When a resource is deleted, its identifier is tombstoned. A tombstoned identifier:

* Cannot be reused for a new resource
* Returns an appropriate HTTP status code if accessed
* Prevents identity confusion if a new resource is later created at the same path

## PII Leakage Mitigation

These identifiers are opaque, internally managed values. Unlike path-based URLs that may contain usernames or other identifying information, identifiers do not reveal any personally identifiable information. This makes them safe to use in:

* Audit event records
* External system references
* Access Grant credentials
* Logging and monitoring systems
* AI agent context stores

## Audit Events

ESS 3.0 audit events include identifiers for all referenced resources. This provides a consistent, durable reference in audit trails that remains valid even after infrastructure changes.