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

# Credentials

> Retrieve, verify, and present W3C Verifiable Credentials and SD-JWT selective disclosures.

## Overview

The `credentials` client manages W3C Verifiable Credentials and SD-JWT selective disclosures. Retrieve individual credentials, list with filters, verify credential JWTs, and create selective-disclosure presentations.

Access the credentials client via `client.credentials`.

## Get

Retrieve a single Verifiable Credential by its ID.

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    vc = client.credentials.get("vc_01HXYZ...")

    print(f"ID: {vc.id}")
    print(f"Type: {vc.type}")
    print(f"Issuer: {vc.issuer}")
    print(f"Subject: {vc.subject}")
    print(f"Status: {vc.status}")
    print(f"Issued: {vc.issuance_date}")
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `credential_id` | `str` | Yes | The unique credential identifier. |

### VerifiableCredential

| Field | Type | Description |
| - | - | - |
| `id` | `str` | Unique credential identifier. |
| `type` | `tuple[str, ...]` | Credential types (always includes `'VerifiableCredential'`). |
| `issuer` | `str` | DID of the credential issuer. |
| `subject` | `str` | DID of the credential subject (the holder). |
| `issuance_date` | `str` | ISO 8601 timestamp when the credential was issued. |
| `expiration_date` | `str \| None` | ISO 8601 expiration timestamp, or `None` if no expiry. |
| `status` | `str` | Current status: `'active'`, `'revoked'`, or `'expired'`. |
| `jwt` | `str` | The credential in compact JWT format. |
| `claims` | `dict[str, Any]` | The credential subject claims. |

## List

List Verifiable Credentials with optional filters.

```python theme={null}
from grantex import Grantex, ListCredentialsParams

with Grantex(api_key="gx_live_...") as client:
    result = client.credentials.list(ListCredentialsParams(
        principal_id="user_abc123",
        type="IdentityCredential",
        status="active",
        page=1,
        page_size=20,
    ))

    print(f"Total: {len(result.credentials)}")
    for vc in result.credentials:
        print(f"  {vc.id}: {vc.type}")
```

### ListCredentialsParams

| Parameter | Type | Required | Description |
| - | - | - | - |
| `principal_id` | `str \| None` | No | Filter credentials by principal (subject) ID. |
| `type` | `str \| None` | No | Filter by credential type (e.g., `'IdentityCredential'`). |
| `status` | `str \| None` | No | Filter by status: `'active'`, `'revoked'`, `'expired'`. |
| `page` | `int \| None` | No | Page number for pagination (default: 1). |
| `page_size` | `int \| None` | No | Results per page (default: 20, max: 100). |

### ListCredentialsResponse

| Field | Type | Description |
| - | - | - |
| `credentials` | `list[VerifiableCredential]` | List of Verifiable Credential objects. |
| `total` | `int` | Total number of matching credentials. |

## Verify

Verify a Verifiable Credential JWT. Checks signature, expiration, revocation status, and issuer trust chain.

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    result = client.credentials.verify("eyJhbGciOiJFUzI1NiIs...")

    if result.valid:
        print(f"Issuer: {result.issuer}")
        print(f"Subject: {result.subject}")
        print(f"Claims: {result.claims}")
        print(f"Expires at: {result.expires_at}")
    else:
        print(f"Invalid: {result.reason}")
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `vc_jwt` | `str` | Yes | The Verifiable Credential in compact JWT format. |

### VerifyCredentialResponse

| Field | Type | Description |
| - | - | - |
| `valid` | `bool` | Whether the credential is valid. |
| `issuer` | `str \| None` | DID of the issuer (present when valid). |
| `subject` | `str \| None` | DID of the subject (present when valid). |
| `claims` | `dict[str, Any] \| None` | Credential subject claims (present when valid). |
| `expires_at` | `str \| None` | ISO 8601 expiration timestamp. |
| `reason` | `str \| None` | Reason for invalidity: `'expired'`, `'revoked'`, `'invalid_signature'`, `'untrusted_issuer'`. |

## Present

Create a selective-disclosure presentation from an SD-JWT. Only the specified claims are disclosed.

```python theme={null}
from grantex import Grantex, PresentCredentialParams

with Grantex(api_key="gx_live_...") as client:
    presentation = client.credentials.present(PresentCredentialParams(
        sd_jwt="eyJ0eXAiOiJ2YytzZC1qd3QiLC...",
        disclosed_claims=["name", "email"],
        audience="did:web:verifier.example.com",
        nonce="unique-request-nonce",
    ))

    print(f"Presentation JWT: {presentation.presentation_jwt}")
    print(f"Disclosed: {presentation.disclosed_claims}")
    print(f"Holder binding: {presentation.holder_binding}")
```

### PresentCredentialParams

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sd_jwt` | `str` | Yes | The SD-JWT credential to create a presentation from. |
| `disclosed_claims` | `list[str]` | Yes | Claim names to disclose. All others remain hidden. |
| `audience` | `str \| None` | No | Intended verifier DID or URL for the holder binding. |
| `nonce` | `str \| None` | No | Nonce for replay protection in the holder binding. |

### PresentCredentialResponse

| Field | Type | Description |
| - | - | - |
| `presentation_jwt` | `str` | The SD-JWT presentation containing only the disclosed claims. |
| `disclosed_claims` | `list[str]` | The claim names that were disclosed. |
| `holder_binding` | `str` | The key binding JWT proving holder possession. |

## Example: Credential Lifecycle

```python theme={null}
from grantex import Grantex, ListCredentialsParams, PresentCredentialParams

with Grantex(api_key="gx_live_...") as client:
    # List active credentials for a user
    result = client.credentials.list(ListCredentialsParams(
        principal_id="user_abc123",
        status="active",
    ))

    # Verify a specific credential
    vc = result.credentials[0]
    verification = client.credentials.verify(vc.jwt)
    if not verification.valid:
        raise ValueError(f"Credential invalid: {verification.reason}")

    # Create a selective-disclosure presentation
    presentation = client.credentials.present(PresentCredentialParams(
        sd_jwt=vc.jwt,
        disclosed_claims=["name", "email"],
        audience="did:web:verifier.example.com",
        nonce="unique-request-nonce",
    ))

    # Send presentation.presentation_jwt to the verifier
    print(f"Presentation ready: {len(presentation.disclosed_claims)} claims disclosed")
```

## Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.