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

# Grant Decrypt Access

> Issue a short-lived access token (2-3 minutes) for receipt decryption.
The source IP is logged for audit purposes. Maximum 5 active tokens per user.




## OpenAPI

````yaml post /api/v1/keys/grant-access
openapi: 3.1.0
info:
  title: Digital Receipt Protocol API
  description: >
    The Digital Receipt Protocol (DRP) provides a secure, end-to-end encrypted
    digital receipt system

    for banks, merchants, and fintech applications. This API enables secure
    receipt encryption,

    decryption, and storage with robust key management and access control.


    ## Key Features

    - **End-to-End Encryption**: AES-256-GCM for receipt data with
    RSA-OAEP-SHA256 key wrapping

    - **User Onboarding**: Generate key pairs and register users with hashed PAN
    identifiers

    - **Access Control**: Short-lived access tokens (2-3 minutes) for receipt
    decryption

    - **Escrow Support**: Encrypted receipts for non-onboarded users via escrow
    keys

    - **Payment Gateway Integration**: Store receipts with transaction mappings
    for Stripe, Square, etc.

    - **Audit Logging**: Comprehensive tracking of all cryptographic operations


    ## Pricing Format

    All monetary values are represented in the smallest currency unit (e.g.,
    cents for USD).

    Example: $42.00 = 4200
  version: 1.0.0
  contact:
    name: Digital Receipt Protocol Team
    url: https://digitalreceiptprotocol.org
    email: api@digitalreceiptprotocol.org
  license:
    name: GNU General Public License v3.0
    url: https://www.gnu.org/licenses/gpl-3.0.html
servers:
  - url: https://api.digitalreceiptprotocol.org
    description: Production server
  - url: https://staging-api.digitalreceiptprotocol.org
    description: Staging server
  - url: http://localhost:3000
    description: Local development server
security: []
tags:
  - name: Health
    description: Service health monitoring
  - name: Onboarding
    description: User registration and key generation
  - name: Keys
    description: Key management and access control
  - name: Receipts
    description: Receipt encryption and decryption
  - name: Transactions
    description: Transaction storage and retrieval
  - name: Payments
    description: Payment gateway integration (Stripe, Square)
paths:
  /api/v1/keys/grant-access:
    post:
      tags:
        - Keys
      summary: Grant decrypt access
      description: >
        Issue a short-lived access token (2-3 minutes) for receipt decryption.

        The source IP is logged for audit purposes. Maximum 5 active tokens per
        user.
      operationId: grantAccess
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantAccessRequest'
            example:
              userId: usr_f8e7d6c5-b4a3-4c2d-1e0f-9a8b7c6d5e4f
              keyId: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
      responses:
        '200':
          description: Access granted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantAccessResponse'
              example:
                success: true
                data:
                  tokenId: tok_9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4
                  userId: usr_f8e7d6c5-b4a3-4c2d-1e0f-9a8b7c6d5e4f
                  keyId: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  purpose: decrypt
                  grantedAt: '2025-12-18T10:35:00Z'
                  expiresAt: '2025-12-18T10:38:00Z'
                  sourceIp: 192.168.1.100
        '400':
          description: Grant request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: GRANT_ERROR
                  message: Failed to grant access
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    GrantAccessRequest:
      type: object
      required:
        - userId
        - keyId
      properties:
        userId:
          type: string
          format: uuid
          description: User ID requesting access
          example: 550e8400-e29b-41d4-a716-446655440001
        keyId:
          type: string
          format: uuid
          description: Key ID to grant access for
          example: 550e8400-e29b-41d4-a716-446655440000
    GrantAccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            tokenId:
              type: string
              format: uuid
              description: Access token ID
              example: 550e8400-e29b-41d4-a716-446655440002
            userId:
              type: string
              format: uuid
              example: 550e8400-e29b-41d4-a716-446655440001
            keyId:
              type: string
              format: uuid
              example: 550e8400-e29b-41d4-a716-446655440000
            purpose:
              type: string
              enum:
                - decrypt
                - sign
              example: decrypt
            grantedAt:
              type: string
              format: date-time
              example: '2025-12-15T12:00:00Z'
            expiresAt:
              type: string
              format: date-time
              description: Token expires in 2-3 minutes (180 seconds)
              example: '2025-12-15T12:03:00Z'
            sourceIp:
              type: string
              description: IP address of the requester (for audit)
              example: 192.168.1.1
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
            details:
              type: object
              description: Additional error details
              additionalProperties: true

````