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

# Validate the API key and return its tenant + scopes

> Any valid (non-revoked, non-expired) key works; no scope required.



## OpenAPI

````yaml /openapi.yaml get /v1/me
openapi: 3.0.3
info:
  title: myproceeds API
  version: 1.1.0
  description: |
    Public REST API for the myproceeds (x402) commerce platform.

    Tenants use this API to programmatically manage their Services and
    Paywalls. Authentication is via API keys generated from the dashboard.

    ## Authentication

    Send the API key in one of two ways:

      Authorization: Bearer mpk_<64 hex chars>
      X-Api-Key: mpk_<64 hex chars>

    Key format: `mpk_` prefix followed by 64 lowercase hex characters
    (32 random bytes). The raw key is only shown once at creation and
    cannot be recovered later.

    ## Scopes

    Each key carries a set of scopes that determine which endpoints it
    can call:

      - `services:read`     — read services
      - `services:write`    — create/update/delete services (implies read)
      - `paywalls:read`     — read paywalls
      - `paywalls:write`    — create/update/delete paywalls (implies read)
      - `transactions:read` — read payment transactions
      - `events:read`       — read analytics events

    Use `GET /v1/me` to validate a key and inspect the tenant and scopes
    it carries.

    ## Secret handling

    Secret material — service `authConfig` values and paywall custom header
    values — is always masked as `"***"` in API responses. Field names (keys)
    are returned so you can see what is configured; the plaintext values are
    never exposed by the public API.

    ## Rate limits

    Each API key may make up to 1000 requests per 60-second window.
    When exceeded the API responds with `429 Too Many Requests` and a
    `Retry-After` header indicating seconds to wait.

    ## Response envelope

    Successful responses return:

      { "data": ..., "meta": { "requestId": "...", "timestamp": "..." } }

    Lists additionally include `meta.pagination`:

      { "total": N, "limit": L, "offset": O, "hasMore": bool }

    Errors return a `meta.requestId` you can quote to support, which
    correlates with the server log line:

      { "error": "message", "code": "MACHINE_CODE", "details": ...,
        "meta": { "requestId": "...", "timestamp": "..." } }
servers:
  - url: https://api.myproceeds.xyz
    description: Current environment
security:
  - ApiKeyAuth: []
tags:
  - name: Identity
    description: >-
      API-key authenticated endpoint to validate a key and read its
      tenant/scopes
  - name: Services
    description: API-key authenticated CRUD for tenant services
  - name: Paywalls
    description: API-key authenticated CRUD for tenant paywalls
  - name: Data
    description: API-key authenticated read-only access to transactions and analytics
  - name: System
    description: Unauthenticated service health endpoints
paths:
  /v1/me:
    get:
      tags:
        - Identity
      summary: Validate the API key and return its tenant + scopes
      description: Any valid (non-revoked, non-expired) key works; no scope required.
      responses:
        '200':
          description: Key identity
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          user:
                            type: object
                            properties:
                              id:
                                type: string
                              email:
                                type: string
                                nullable: true
                              name:
                                type: string
                                nullable: true
                              walletAddress:
                                type: string
                                nullable: true
                                pattern: ^0x[a-fA-F0-9]{40}$
                                description: |
                                  The tenant's primary wallet address (falls
                                  back to their earliest-linked wallet). `null`
                                  when no wallet is linked yet.
                          apiKey:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              scopes:
                                type: array
                                items:
                                  $ref: '#/components/schemas/Scope'
                              keyPrefix:
                                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Envelope:
      type: object
      required:
        - data
        - meta
      properties:
        data: {}
        meta:
          $ref: '#/components/schemas/Meta'
    Scope:
      type: string
      enum:
        - services:read
        - services:write
        - paywalls:read
        - paywalls:write
        - transactions:read
        - events:read
    Meta:
      type: object
      properties:
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
        - code
        - meta
      properties:
        error:
          type: string
          description: Human-readable message
        code:
          type: string
          description: Machine-readable code
          enum:
            - INVALID_API_KEY
            - KEY_REVOKED
            - KEY_EXPIRED
            - KEY_INACTIVE
            - INSUFFICIENT_SCOPE
            - IP_NOT_ALLOWED
            - RATE_LIMITED
            - NOT_FOUND
            - FORBIDDEN
            - VALIDATION_ERROR
            - CONFLICT
            - KEY_LIMIT_REACHED
            - SSRF_BLOCKED
            - ALREADY_REVOKED
            - INVALID_WALLET
            - INVALID_SERVICE
            - BETA_LIMIT_PAYWALLS
            - BETA_LIMIT_SERVICES
            - INTERNAL_ERROR
            - DATABASE_ERROR
        details:
          description: Optional machine-readable detail (e.g. Zod issues)
        meta:
          $ref: '#/components/schemas/Meta'
  responses:
    Unauthorized:
      description: API key missing, invalid, revoked, or expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Valid API key required
            code: INVALID_API_KEY
    RateLimited:
      description: Rate limit exceeded (1000 requests/minute per key)
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the limit resets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: |
        API key in format `mpk_<64 hex chars>`. Can alternatively be sent as
        `Authorization: Bearer mpk_...`.

````