> ## 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.

# Header Reference

> HTTP headers used for Sumvin identity credential transmission

This page documents the HTTP headers that carry a user's <Tooltip headline="Sigil" tip="Sumvin's portable, KYC-verified identity — Proof of Personhood." cta="Glossary →" href="/glossary">Sigil</Tooltip> credential from their request to your service as a verifier, and the headers you use when calling SIS yourself.

Every inbound credential is a <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> — the cryptographic authorisation the user signed. A Stamped Mandate is delivered over the API as a `PINT` (header `x-sumvin-pint-token`); the header names on this page are the wire contract and stay exactly as written.

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

<Note>
  Two credentials, two headers. Inbound user requests carry the **PINT JWT** in `x-sumvin-pint-token`. Outbound calls to SIS (revocation checks, JWKS fetches, token exchange) use your **SIS API key** in `Authorization: Bearer`. Do not conflate them.
</Note>

## Identity Headers (Inbound)

These headers arrive on requests from a user's client (or an upstream SIS API caller) to your service, and carry the user's Stamped Mandate.

### X-Sumvin-Pint-Token

```
x-sumvin-pint-token: <jwt>
```

Present on **all** requests carrying Sumvin credentials (both Standard and Enhanced tier). Contains the SIS-signed PINT JWT as a raw compact-serialized JWT — no `Bearer` prefix.

| Property     | Value                                   |
| ------------ | --------------------------------------- |
| Required     | Yes                                     |
| Format       | Compact-serialized JWT (no prefix)      |
| Verification | Validate against [JWKS](/merchant/jwks) |

### X-Pint-Signature

```
X-Pint-Signature: 0x...
```

Present only on **Enhanced tier** requests. Contains the hex-encoded EIP-712 signature from the original Purchase Intent.

| Property     | Value                                                      |
| ------------ | ---------------------------------------------------------- |
| Required     | Enhanced tier only                                         |
| Format       | Hex-encoded signature with `0x` prefix                     |
| Verification | Recover the signer address via EIP-712 typed data recovery |

### X-Pint-Payload

```
X-Pint-Payload: eyJ3YWxsZXQiOiIweEUyM2M5QTcwQkM3NDlFQmRkZDhj...
```

Present only on **Enhanced tier** requests. Contains the base64-encoded JSON of the signed PINT payload.

| Property | Value                                                  |
| -------- | ------------------------------------------------------ |
| Required | Enhanced tier only                                     |
| Format   | Base64-encoded JSON object                             |
| Content  | The [PurchaseIntent](/identity/pint) payload as signed |

**Decoded example:**

```json theme={null}
{
  "wallet": "0xE23c9A70BC749EBddd8c78a864fd911D04E9e992",
  "nonce": 42,
  "statement": "Purchase authorization for partner X",
  "scopes": ["sr:us:pint:identity:proof_of_personhood", "sr:us:pint:spend:execute"],
  "resources": ["sr:us:pint:abc123"],
  "maxAmount": 10000,
  "maxAmountToken": "0x0000000000000000000000000000000000000000",
  "expiresAt": 1740000000
}
```

## SIS API Key (Outbound)

When **you** call authenticated SIS endpoints (for example, to check PINT revocation status or exchange a signed PINT for a JWT), authenticate with your SIS API key using the `Authorization` header. The [JWKS endpoint](/merchant/jwks) is the one exception — it is public and must be called without this header.

```
Authorization: Bearer <SIS_API_KEY>
```

| Property | Value                                                                                                                                                                                                   |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Required | Yes, for authenticated outbound calls to SIS (all except the JWKS endpoint, which is public)                                                                                                            |
| Format   | `Bearer ` followed by the API key issued to you during partner onboarding                                                                                                                               |
| Used on  | [Revocation checks](/merchant/revocation), [token exchange](/identity/token-exchange). The [JWKS endpoint](/merchant/jwks) is publicly accessible and must be called without an `Authorization` header. |

<Warning>
  Never forward a user's PINT JWT in the `Authorization` header. The PINT JWT belongs in `x-sumvin-pint-token`. The `Authorization: Bearer` header is reserved for your SIS API key on outbound calls.
</Warning>

## Header Presence by Tier

| Header                | Standard (Tier 1) | Enhanced (Tier 2) |
| --------------------- | ----------------- | ----------------- |
| `x-sumvin-pint-token` | Present           | Present           |
| `X-Pint-Signature`    | Absent            | Present           |
| `X-Pint-Payload`      | Absent            | Present           |

## Detecting the Tier

You can determine the verification tier from either the JWT claims or the presence of headers:

**From JWT claims (preferred):**

```typescript theme={null}
const tier = jwtPayload.verification_tier; // "standard" or "enhanced"
```

**From header presence:**

```typescript theme={null}
const isEnhanced =
  request.headers.has("x-pint-signature") &&
  request.headers.has("x-pint-payload");
```

If the JWT claims `"enhanced"` but the PINT headers are missing, reject the request — the credentials are incomplete.