Credential Request

The core specification within a Credential Request, formally defining what a Holder must prove. It uses a Presentation Definition object (as per the W3C Presentation Exchange specification) to specify:

• Required Credential Types (e.g., a UniversityDegreeCredential)
• Constraints on specific claims (e.g., degree.type must equal "Bachelor")
• Proof Formats accepted (e.g., JSON Web Token, Data Integrity Proofs)

Security mechanisms to prevent replay attacks and ensure the response is intended for this specific request.

• Challenge (nonce): A unique, random string the Holder must sign in their response, proving the response is fresh and not reused.
• Domain: A URI (e.g., https://service.example.com) identifying the Verifier, which the Holder must include in their signature, binding the response to this specific requesting party.

A privacy-preserving feature enabled by the request format. It allows a Holder to reveal only the specific claims required, not the entire credential. For example, a request for proof of age over 21 can be satisfied with a zero-knowledge proof or a BBS+ signature-derived proof, revealing only the validity of the statement without disclosing the exact birth date.

Metadata establishing the legitimacy of the request.

• Verifier's Decentralized Identifier (DID): The cryptographic identifier of the entity making the request, allowing the Holder to authenticate the Verifier.
• Purpose Statement: A human- and machine-readable explanation of why the data is being requested (e.g., "To verify eligibility for a premium service tier"), promoting transparency and user consent.

The request specifies which credential and proof formats the Verifier's system can process. Common formats include:

• JWT-VC / JWT-VP (JSON Web Token for Verifiable Credentials/Presentations)
• SD-JWT (Selective Disclosure for JWT)
• LDP-VC (Linked Data Proof Verifiable Credentials) This allows interoperability between different wallet and verifier implementations.

Technical details for the Holder's wallet on how to submit the Verifiable Presentation. This typically includes:

• Response Endpoint (callback URL): The HTTPS endpoint where the signed presentation should be submitted.
• Response Type: The expected format of the response (e.g., vp_token as defined by OpenID for Verifiable Credentials).
• State (optional): A session identifier passed from the request to the response, allowing the Verifier to correlate them.

A lending protocol issues a Credential Request for a user's on-chain credit score or transaction history to determine loan eligibility and risk-adjusted interest rates.

• Example: A user applies for an undercollateralized loan. The protocol requests a CreditScoreCredential from a trusted attestation network.
• Data Sources: The credential can aggregate data like repayment history, wallet age, and asset diversity from multiple chains.

A user's reputation or achievements from one platform (e.g., a gaming DAO) can be ported to another via Credential Requests, enabling composable social graphs.

• Example: A freelance marketplace requests a ContributorCredential from a developer's GitHub DAO to verify their proven track record.
• Interoperability: This breaks down data silos, allowing users to build a portable, verifiable identity across Web3.

Regulated DeFi protocols (ReFi) or exchanges use Credential Requests to obtain verified Know Your Customer (KYC) credentials from specialized issuers, without handling raw personal data.

• Example: A compliant DEX requests a KYCClaimCredential from a user's identity wallet before allowing high-value trades.
• Privacy: The user maintains control, sharing only the necessary proof (e.g., "is over 18 and verified") rather than their full ID document.

A Credential Request is a structured data object, often formatted as JSON, that specifies the verifiable credentials a relying party (e.g., a dApp) requires. It defines the type of credential (e.g., Proof of Humanity, KYC attestation), the issuer (trusted entity), and optional predicates (e.g., 'age > 18'). The user's wallet evaluates this request against their held credentials to generate a cryptographic proof.

Credential Requests enable token-gating and access control for web3 applications.

• A DeFi protocol can request a credential proving the user is not a sanctioned entity before allowing a trade.
• A DAO's governance portal can request a credential proving membership to unlock voting.
• An NFT community can gate a Discord channel by requesting proof of ownership of a specific NFT, verified via a credential.

The W3C Verifiable Credentials (VC) Data Model provides the foundation. A request is often implemented as a Presentation Definition within the Decentralized Identity Foundation (DIF)'s Presentation Exchange specification. This standardizes how to request credentials, describe constraints, and format the resulting Verifiable Presentation that is shared back.

The user experience follows a clear sequence:

1. Request: A dApp sends a Credential Request to the user's wallet.
2. Evaluation: The wallet scans its stored credentials for a match.
3. Consent: The wallet UI shows the user what is being requested and by whom.
4. Response: If the user consents, the wallet creates a Verifiable Presentation—a cryptographically signed package containing the required proof—and sends it back to the requester.

Credential Requests are designed for data minimization and selective disclosure.

• Zero-Knowledge Proofs (ZKPs): A user can prove they hold a credential meeting a condition (e.g., 'age > 21') without revealing their birth date or the credential's full contents.
• DID Association: Requests are tied to a user's Decentralized Identifier (DID), preventing correlation across different services unless explicitly intended by the user.

Sign-In with Ethereum (EIP-4361) is a foundational credential request. When a website asks you to 'Sign In with Ethereum,' it sends a request for a specific credential: a cryptographic signature from your Ethereum address. This proves control of the address, which can then be linked to other on-chain or off-chain credentials in your wallet, creating a portable identity layer without passwords.

A core privacy principle where a verifier requests only the specific attributes needed for verification, not the entire credential. This prevents unnecessary data exposure.

• Zero-Knowledge Proofs (ZKPs): Allow users to prove a claim (e.g., age > 21) without revealing their birth date.
• BBS+ Signatures: Enable selective disclosure of specific fields from a signed credential.
• Example: Proving residency in a jurisdiction by revealing only a country code, not a full address.

The entity requesting credentials must be authenticated to prevent phishing and impersonation attacks. Users need assurance they are sharing data with a legitimate party.

• Decentralized Identifiers (DIDs): Verifiers can present their own DIDs, allowing users to check their status on a verifiable data registry.
• Trust Frameworks: Legal or industry-accredited frameworks (e.g., GAIN) define rules for accredited verifiers.
• Risk: An unauthenticated request can lead to credential theft or fraudulent access.

The presentation request itself—the data structure specifying what is being asked for—must be tamper-proof and clearly understood by the user's wallet.

• Cryptographic Nonce: Prevents replay attacks by ensuring a request can only be used once.
• Human-Readable Descriptions: The request should clearly state the verifier's name and the purpose of the data collection.
• Standard Formats: Using W3C Verifiable Presentation Request formats ensures interoperability and reduces parsing errors that could lead to data leakage.

The credential request process must obtain explicit, informed consent from the user and create a record of the transaction for auditing.

• Informed Consent UI: Wallets should display what data is requested, by whom, and for what purpose before approval.
• Verifiable Presentations: The user's response is a signed Verifiable Presentation, providing cryptographic proof of consent for that specific request.
• Auditability: This creates a non-repudiable log for both parties, crucial for regulatory compliance (e.g., GDPR).

A major privacy risk is a verifier using credential requests to link a user's activity across different services or sessions.

• Unlinkable Presentations: Techniques like ZKPs and blinding can prevent a verifier from correlating multiple presentations from the same user.
• Unique Session Identifiers: Each request/response pair should use unique, ephemeral identifiers not tied to a user's master DID.
• Pseudonymity: Users may employ different pairwise DIDs for different verifiers to compartmentalize their digital identity.

Security measures to ensure a presented credential is bound to the legitimate holder and cannot be replayed by an attacker.

• Holder Binding: Credentials are cryptographically bound to a user's DID key, preventing presentation by anyone else.
• Challenge-Response: The verifier includes a unique challenge (nonce) in the request that must be signed in the user's response.
• Expiration Timestamps: Requests and presentations have short validity windows to limit the attack surface for replay.

A Verifiable Credential is a tamper-evident, cryptographically signed digital attestation of a claim. It is the primary data object requested in a Credential Request. VCs are issued by trusted entities and can represent identity attributes, qualifications, or permissions.

• Structure: Typically follows the W3C standard, containing metadata, claims, and proofs.
• Key Property: Enables selective disclosure, allowing users to share only the necessary information from a credential.

A Decentralized Identifier is a globally unique, cryptographically verifiable identifier controlled by the subject (e.g., a user or organization). DIDs are foundational for credential requests as they identify the holder (who presents credentials) and the verifier (who requests them).

• Format: did:method:identifier (e.g., did:ethr:0x...).
• Control: Resolves to a DID Document containing public keys and service endpoints for authentication.

A Presentation Definition is a formal, machine-readable specification that defines the exact requirements a verifier has for the credentials it will accept. It is the technical blueprint for a Credential Request.

• Contents: Specifies the type of credentials required, the specific claims needed, and any constraints (e.g., issuer trust framework).
• Standard: Defined by the Decentralized Identity Foundation (DIF) as part of the Presentation Exchange protocol.

A Verifiable Presentation is the packaged response to a Credential Request. It is a cryptographically signed container, created by the holder, that bundles one or more Verifiable Credentials and proves control over the associated DID.

• Purpose: Enables the holder to satisfy a verifier's Presentation Definition.
• Security: The VP's signature provides data integrity and authentication, proving the credentials were not tampered with and are presented by their rightful owner.

The Holder is the entity (user, device, or organization) that possesses one or more Verifiable Credentials and controls the associated Decentralized Identifiers (DIDs). In a Credential Request flow, the holder receives the request, selects the appropriate credentials from their digital wallet, and creates a Verifiable Presentation in response.

• Key Role: Acts as the intermediary between Issuers and Verifiers, maintaining data sovereignty.

The Verifier is the entity that requests and validates credentials to grant access, verify eligibility, or complete a transaction. It initiates the Credential Request by sending a Presentation Definition to the holder.

• Core Function: After receiving a Verifiable Presentation, the verifier cryptographically verifies the signatures of the presentation and the contained credentials, and checks that the claims satisfy its business logic.
• Example: A DeFi protocol acting as a verifier requests a credential proving a user is not from a sanctioned jurisdiction.