> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sumvin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sumvin Resource Identifiers (SRI)

> Format and usage of SRI URIs for identifying users and resources

Every user and resource in the Sumvin ecosystem is addressed by a **<Tooltip headline="SRI" tip="Sumvin Resource Identifier — URI-style identifier for users and capabilities." cta="Glossary →" href="/glossary">Sumvin Resource Identifier</Tooltip> (SRI)** — a URI-style string that uniquely identifies the resource and encodes its type and resolution path. SRIs are the identifier backbone of <Tooltip headline="Sigil" tip="Sumvin's portable, KYC-verified identity — Proof of Personhood." cta="Glossary →" href="/glossary">Sigil</Tooltip>, Sumvin's portable identity. The scheme is stable, deterministic, and human-legible — the same SRI is used in JWT claims, API paths, and signed PINT payloads.

<Snippet file="product-term-disambiguation.mdx" />

## The three SRI families

SRIs come in three shapes, disambiguated by segment count and position.

| Family                | Example                                                | What it names                                                                                                                                                                                                                                           |
| --------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User SRI**          | `sr:us:person:safe:0xE23c…9e992`                       | A Sumvin user, resolved by their Safe address                                                                                                                                                                                                           |
| **PINT resource SRI** | `sr:us:pint:abc123def456`                              | A specific <Tooltip headline="Stamped Mandate" tip="A signed authorisation a user grants for specific scoped actions — delivered on the wire as a PINT." cta="Glossary →" href="/glossary">Stamped Mandate</Tooltip>, delivered on the wire as a `PINT` |
| **Scope SRI**         | `sr:us:pint:spend:execute?max=10000000&asset=USDC@sei` | A capability a Stamped Mandate is requesting                                                                                                                                                                                                            |

Scope SRIs and PINT resource SRIs share the `sr:us:pint:…` prefix but are shaped differently — scope SRIs have a `{domain}:{action}` pair and optional query params; resource SRIs are a single opaque ID. Parsers distinguish the two by segment count.

## Where you see SRIs

* **JWT `sub` claim** — the user's SRI
* **JWT `pint_uri` claim** — the PINT resource SRI
* **JWT `scopes` claim** — an array of scope SRIs
* **PINT payload `scopes` field** — the same scope SRIs, signed verbatim
* **SIS lookup paths** — `/v0/users/{sri}` takes a user SRI (URL-encoded)

## Format

```
sr:{region}:{resource_type}:{sub_type}:{identifier}
```

| Segment         | Description                    | Examples                |
| --------------- | ------------------------------ | ----------------------- |
| `sr`            | Protocol prefix (always `sr`)  | —                       |
| `region`        | Geographic region code         | `us`, `eu`, `gb`        |
| `resource_type` | The kind of resource           | `person`, `pint`        |
| `sub_type`      | Resolution method or qualifier | `safe`, `eoa`           |
| `identifier`    | The unique value               | Wallet address, PINT ID |

## Common SRI Patterns

### User SRIs

Users are identified by their wallet address. The sub-type indicates which wallet type is used for resolution:

```
sr:us:person:safe:0xE23c9A70BC749EBddd8c78a864fd911D04E9e992
sr:us:person:eoa:0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78
```

The `safe` sub-type is the canonical identifier for most operations, as the Safe smart wallet is the user's primary identity anchor.

### PINT SRIs

Purchase Intents are identified by a generated PINT ID:

```
sr:us:pint:abc123def456
```

PINT SRIs appear in JWT claims (`sub`, `pint_uri`), API responses, and revocation checks.

### Scope SRIs

Scope SRIs are a third URI family in the same scheme — they identify **capabilities** rather than users or resources. A scope SRI is the string form of a PINT's requested permission; partners consume them via the `scopes` claim on the exchanged JWT.

```
sr:{region}:pint:{domain}:{action}[?{key}={value}&{key}={value}]
```

| Scope SRI                                                            | Grants                                            |
| -------------------------------------------------------------------- | ------------------------------------------------- |
| `sr:us:pint:sigil:kyc_status`                                        | Attest the user's KYC status                      |
| `sr:us:pint:spend:execute?max=10000000&asset=USDC@sei&chain_id=1329` | Authorise on-chain spend up to 10 USDC on Sei     |
| `sr:us:pint:errand:search?time=2592000`                              | Create an IPA with a 30-day search window         |
| `sr:us:pint:accounts:link?provider=meld`                             | Link a bank account via the bank-linking provider |

<Note>
  Scope SRIs are distinct from **PINT resource SRIs** (e.g. `sr:us:pint:abc123def456`). Both use the `sr:…:pint:…` prefix, but they differ in shape and purpose:

  * **Scope SRI** — 5 fixed segments (`sr`, region, `pint`, domain, action) plus optional `?k=v` query params. The third segment `pint` is the disambiguator that marks the URI as a scope rather than a PINT resource.
  * **PINT resource SRI** — 4 segments (`sr`, region, `pint`, PINT ID), no query params.

  Parsers use the segment count and the presence of the `{domain}:{action}` pair to disambiguate the two families.
</Note>

Scope SRIs support per-scope parameters for fine-grained capability envelopes — amount caps in base units, asset + chain context as `SYMBOL@context`, provider choices as enums, and time windows / timestamps in unix seconds. See the [Scopes Reference](/identity/scopes) for the full scope catalog, parameter conventions, and verification-tier mapping.

## Using SRIs

### Looking Up Users via SIS

Pass an SRI to the SIS user lookup endpoint to retrieve user data. The fields returned depend on your API key's authorisation level:

```bash theme={null}
curl https://sis.sumvin.com/v0/users/sr:us:person:safe:0xE23c9A70BC749EBddd8c78a864fd911D04E9e992 \
  -H "Authorization: Bearer <your-api-key>"
```

```json theme={null}
{
  "sri": "sr:us:person:safe:0xE23c9A70BC749EBddd8c78a864fd911D04E9e992",
  "user": {
    "external_id": "usr_abc123",
    "account_status": "active",
    "email": "alice@example.com",
    "username": "alice"
  },
  "_links": {
    "self": {
      "href": "/sis/v0/users/sr:us:person:safe:0xE23c9A70BC749EBddd8c78a864fd911D04E9e992",
      "method": "GET"
    }
  }
}
```

### SRIs in JWTs

When the SIS issues a JWT for a PINT exchange, the `sub` claim contains the user's SRI and the `pint_uri` claim contains the PINT's SRI:

```json theme={null}
{
  "sub": "sr:us:person:safe:0xE23c9A70BC749EBddd8c78a864fd911D04E9e992",
  "pint_uri": "sr:us:pint:abc123def456",
  "aud": "partner-x.example.com"
}
```

## URL Encoding

When SRIs appear in URL paths, the colon separators must be URL-encoded as `%3A`:

```
GET /sis/v0/users/sr%3Aus%3Aperson%3Asafe%3A0xE23c9A70BC749EBddd8c78a864fd911D04E9e992
```

Most HTTP client libraries handle this encoding automatically.