# Identity \[Verify clients without payment] Every MPP Credential carries a cryptographic identity—the client's public key in the `source` field. Your server gets a verified identity on every request, whether the client pays or not. This page covers how to use that identity for access control, gating, and multi-step workflows. ## Overview The Credential already proves the client controls a specific public key. The `source` field is the same regardless of the payment amount, which means you can use the MPP flow purely for identity when payment isn't needed. Extract the client's identity from any verified request using `Credential.fromRequest`: ```ts twoslash [server.ts] // @noEmit declare const request: Request // ---cut--- import { Credential } from 'mppx' const credential = Credential.fromRequest(request) const clientIdentity = credential.source // @log: "did:pkh:eip155:4217:0x1234..." ``` Backends key workloads, sessions, and access control on this public key. The payment flow is orthogonal to identity, and can be used in combination with other methods. ### Methods | Method | Payment methods | Description | |--------|-----------------|-------------| | [**Zero-dollar auth**](#zero-dollar-auth) | Tempo, Lightning, Solana, Custom | Proves key ownership with no funds transfer | :::info\[More methods coming] Additional identity methods are in development. Check back for updates. ::: ## Zero-dollar auth Zero-dollar auth uses the standard Challenge → Credential flow with the amount set to `0`. The client signs the Challenge to prove key ownership. No funds move on-chain, and no additional protocol extensions are required. For Tempo charge, zero-dollar auth now uses a `proof` Credential payload instead of a real transaction. The client signs a proof message over the Challenge ID, and the server verifies that signature against the `source` DID. :::warning\[Replay protection] By default, a valid zero-dollar proof remains reusable until the Challenge expires. Pass `store` to `tempo.charge()` when you want single-use proof auth. In a multi-instance deployment, use a shared store so every instance sees consumed proofs. ::: >Server: (1) GET /resource Server-->>Client: (2) 402 + Challenge (amount: 0) Note over Client: (3) Sign proof message Client->>Server: (4) GET /resource + Credential Note over Server: (5) Verify proof Server-->>Client: (6) 200 OK `} /> The Credential contains the client's public key and a valid signature, giving the server a verified identity to associate with the request. For Tempo, the server rejects `transaction` and `hash` payloads for zero-amount Challenges and requires `proof`. ### Case study: long-running jobs A service accepts a paid request to start work, then lets the client poll for results using zero-dollar auth. The server keys workloads on the client's public key. ::::steps #### Client submits a job (paid) The client sends a request with payment to create a new job. The Credential includes both payment proof and the client's public key. ```ts twoslash [client.ts] // @noEmit declare const fetch: (url: string) => Promise<{ json(): Promise }> // ---cut--- const response = await fetch('https://api.example.com/v1/jobs') const { jobId } = await response.json() // @log: { jobId: "abc123" } ``` The server records the job and associates it with the client's public key from the Credential. #### Server stores the public key After the payment middleware verifies the Credential, extract the client's identity from the request: ```ts [server.ts] import { Credential } from 'mppx' export async function handler(request: Request) { const result = await mppx.charge({ amount: '1.00' })(request) if (result.status === 402) return result.challenge const credential = Credential.fromRequest(request) const pubkey = credential.source // [!code hl] const jobId = createJob({ owner: pubkey }) // [!code hl] return result.withReceipt(Response.json({ jobId })) } ``` #### Client polls for status (zero-dollar auth) The client polls the job endpoint. The server issues a zero-dollar Challenge—the client signs it to prove they own the same key. ```ts [server.ts] export async function statusHandler(request: Request) { const result = await mppx.charge({ amount: '0' })(request) // [!code hl] if (result.status === 402) return result.challenge const credential = Credential.fromRequest(request) const job = getJob(jobIdFromUrl(request)) if (job.owner !== credential.source) { return Response.json({ error: 'Not your job' }, { status: 403 }) } return result.withReceipt(Response.json({ result: job.result, status: job.status })) } ``` :::: ### Case study: paid unlock with free access A service charges once to unlock a resource, then grants repeated free access tied to the client's identity. This replaces API keys with cryptographic ownership. ::::steps #### Client pays to unlock The client pays once to gain access. The server records the public key as an authorized user. ```ts [server.ts] export async function unlockHandler(request: Request) { const result = await mppx.charge({ amount: '50.00' })(request) if (result.status === 402) return result.challenge const credential = Credential.fromRequest(request) grantAccess({ dataset: 'premium', owner: credential.source }) // [!code hl] return result.withReceipt(Response.json({ status: 'unlocked' })) } ``` #### Client accesses the resource (zero-dollar auth) Subsequent requests use zero-dollar auth. The server checks the client's identity against the access list. ```ts [server.ts] export async function accessHandler(request: Request) { const result = await mppx.charge({ amount: '0' })(request) // [!code hl] if (result.status === 402) return result.challenge const credential = Credential.fromRequest(request) if (!hasAccess({ dataset: 'premium', owner: credential.source })) { return Response.json({ error: 'Not unlocked' }, { status: 403 }) } return result.withReceipt(Response.json({ data: getDataset('premium') })) } ``` :::: ### Case study: multi-step agent workflow An agent orchestrates a pipeline where one paid step kicks off several follow-up steps that only need identity. Each step verifies the same public key to maintain continuity across the workflow. ::::steps #### Agent starts the pipeline (paid) The agent pays to kick off generation. The server returns a pipeline ID tied to the agent's public key. ```ts [server.ts] export async function createPipelineHandler(request: Request) { const result = await mppx.charge({ amount: '5.00' })(request) if (result.status === 402) return result.challenge const credential = Credential.fromRequest(request) const pipelineId = createPipeline({ owner: credential.source }) // [!code hl] return result.withReceipt(Response.json({ pipelineId })) } ``` #### Agent retrieves intermediate results (zero-dollar auth) The agent polls each stage of the pipeline. Every request proves the same identity without additional payment. ```ts [server.ts] export async function stageHandler(request: Request) { const result = await mppx.charge({ amount: '0' })(request) // [!code hl] if (result.status === 402) return result.challenge const credential = Credential.fromRequest(request) const pipeline = getPipeline(pipelineIdFromUrl(request)) if (pipeline.owner !== credential.source) { return Response.json({ error: 'Not your pipeline' }, { status: 403 }) } const stage = pipeline.stages[stageFromUrl(request)] return result.withReceipt(Response.json({ output: stage.output, status: stage.status })) } ``` #### Agent downloads the final artifact (zero-dollar auth) The final download also uses zero-dollar auth—the server already collected payment at the start. ```ts [server.ts] export async function resultHandler(request: Request) { const result = await mppx.charge({ amount: '0' })(request) // [!code hl] if (result.status === 402) return result.challenge const credential = Credential.fromRequest(request) const pipeline = getPipeline(pipelineIdFromUrl(request)) if (pipeline.owner !== credential.source) { return Response.json({ error: 'Not your pipeline' }, { status: 403 }) } return result.withReceipt(Response.json({ result: pipeline.finalResult })) } ``` ::::