{
  "openapi": "3.1.0",
  "info": {
    "title": "Password Manager Integration API",
    "version": "1.0.0",
    "description": "Commercial integration API. Applications ask a user for a specific secret; the user approves on their phone and the phone encrypts the selected fields for the application's X25519 key. The server only relays ciphertext. An API subscription never buys access to anyone's vault. See https://password-manager.in/developers/docs/ for the encrypted-delivery format, metering and errors.",
    "contact": {"email": "info@password-manager.in"}
  },
  "servers": [{"url": "https://password-manager.in/api/v1"}],
  "security": [{"oauth2": []}],
  "tags": [
    {"name": "OAuth", "description": "Authorization code + PKCE S256. Confidential clients authenticate with a client secret; public (native) clients send client_id only."},
    {"name": "Integration", "description": "Requires an approved application, an active API subscription and the user's grant."},
    {"name": "Public", "description": "No authentication."}
  ],
  "paths": {
    "/oauth/token": {
      "post": {
        "tags": ["OAuth"], "operationId": "token", "security": [],
        "summary": "Exchange an authorization code or rotate a refresh token",
        "requestBody": {"required": true, "content": {"application/x-www-form-urlencoded": {"schema": {"$ref": "#/components/schemas/TokenRequest"}}}},
        "responses": {
          "200": {"description": "Tokens", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TokenResponse"}}}},
          "400": {"description": "invalid_grant / invalid_request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OAuthError"}}}},
          "401": {"description": "invalid_client", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OAuthError"}}}},
          "429": {"$ref": "#/components/responses/RateLimited"}
        }
      }
    },
    "/oauth/revoke": {
      "post": {
        "tags": ["OAuth"], "operationId": "revoke", "security": [],
        "summary": "Revoke an access or refresh token (and its family)",
        "requestBody": {"required": true, "content": {"application/x-www-form-urlencoded": {"schema": {"type": "object", "required": ["client_id", "token"], "properties": {"client_id": {"type": "string"}, "client_secret": {"type": "string"}, "token": {"type": "string"}}}}}},
        "responses": {"200": {"description": "Revoked (also when unknown)"}, "401": {"description": "invalid_client"}}
      }
    },
    "/integration/me": {
      "get": {
        "tags": ["Integration"], "operationId": "me", "security": [{"oauth2": ["identity.basic"]}],
        "summary": "App-specific subject and email of the connected user",
        "responses": {
          "200": {"description": "Identity", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "subject": {"type": "string"}, "email": {"type": "string"}}}}}},
          "default": {"$ref": "#/components/responses/Error"}
        }
      }
    },
    "/integration/secret-requests": {
      "post": {
        "tags": ["Integration"], "operationId": "createSecretRequest", "security": [{"oauth2": ["secret.request"]}],
        "summary": "Ask the user for a secret (the one billable operation)",
        "description": "Billed once per successfully created request (201). Validation errors, replays, limit refusals and server errors are not billed. Send an Idempotency-Key to retry safely: a retry with the same key and body returns the original response without a second charge.",
        "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$"}}],
        "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SecretRequestCreate"}}}},
        "responses": {
          "201": {"description": "Created (pending until the user answers)", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "request": {"$ref": "#/components/schemas/SecretRequest"}}}}}},
          "409": {"description": "replayed_nonce / request_in_progress"},
          "413": {"description": "payload_too_large"},
          "422": {"description": "Validation error, invalid_idempotency_key, idempotency_key_reused"},
          "default": {"$ref": "#/components/responses/Error"}
        }
      }
    },
    "/integration/secret-requests/{id}": {
      "get": {
        "tags": ["Integration"], "operationId": "getSecretRequest", "security": [{"oauth2": ["secret.receive"]}],
        "summary": "Status and, once approved, the encrypted response (not billed)",
        "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}],
        "responses": {
          "200": {"description": "Request", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "request": {"$ref": "#/components/schemas/SecretRequest"}}}}}},
          "404": {"description": "Not found (or not yours)"},
          "default": {"$ref": "#/components/responses/Error"}
        }
      }
    },
    "/integration/shared-items": {
      "get": {
        "tags": ["Integration"], "operationId": "sharedItems", "security": [{"oauth2": ["shared.items.read"]}],
        "summary": "Approvals still retrievable by this app (not billed)",
        "parameters": [{"$ref": "#/components/parameters/Limit"}],
        "responses": {"200": {"description": "Items"}, "default": {"$ref": "#/components/responses/Error"}}
      }
    },
    "/integration/events": {
      "get": {
        "tags": ["Integration"], "operationId": "events", "security": [{"oauth2": ["events.read"]}],
        "summary": "This app's activity for the user (metadata only, not billed)",
        "parameters": [{"$ref": "#/components/parameters/Limit"}],
        "responses": {"200": {"description": "Events"}, "default": {"$ref": "#/components/responses/Error"}}
      }
    },
    "/pricing": {
      "get": {
        "tags": ["Public"], "operationId": "pricing", "security": [],
        "summary": "Published plans and rates (integer minor units)",
        "responses": {"200": {"description": "Catalog"}}
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {"authorizationCode": {
          "authorizationUrl": "https://password-manager.in/oauth/authorize",
          "tokenUrl": "https://password-manager.in/api/v1/oauth/token",
          "refreshUrl": "https://password-manager.in/api/v1/oauth/token",
          "scopes": {
            "identity.basic": "See the account email and a stable app-specific ID",
            "secret.request": "Ask for a specific secret (the user chooses and approves every request)",
            "secret.receive": "Receive approved secrets, encrypted for this app",
            "shared.items.read": "See which approved secrets are still available",
            "events.read": "Read its own activity log for the user"
          }
        }}
      }
    },
    "parameters": {
      "Limit": {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100}, "description": "Page size, capped by your plan's max_page_size."}
    },
    "responses": {
      "Error": {
        "description": "Stable error codes: invalid_token (401), subscription_required (402), subscription_expired (402), insufficient_scope (403), scope_denied (403), rate_limited (429, Retry-After), quota_exceeded (429, Retry-After when time-based), too_many_pending (429), accounting_unavailable (503), service_paused (503).",
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
      },
      "RateLimited": {"description": "rate_limited", "headers": {"Retry-After": {"schema": {"type": "integer"}}}}
    },
    "schemas": {
      "Error": {"type": "object", "required": ["ok", "code", "message"], "properties": {"ok": {"const": false}, "code": {"type": "string"}, "message": {"type": "string"}}},
      "OAuthError": {"type": "object", "properties": {"error": {"type": "string"}, "error_description": {"type": "string"}}},
      "TokenRequest": {"type": "object", "required": ["grant_type", "client_id"], "properties": {
        "grant_type": {"enum": ["authorization_code", "refresh_token"]}, "client_id": {"type": "string"},
        "client_secret": {"type": "string", "description": "Confidential clients only; public clients must not send one."},
        "code": {"type": "string"}, "code_verifier": {"type": "string"}, "redirect_uri": {"type": "string", "description": "Must exactly match a registered URI."},
        "refresh_token": {"type": "string"}}},
      "TokenResponse": {"type": "object", "properties": {"access_token": {"type": "string"}, "token_type": {"const": "Bearer"}, "expires_in": {"type": "integer"}, "refresh_token": {"type": "string"}, "scope": {"type": "string"}}},
      "SecretRequestCreate": {"type": "object", "required": ["purpose", "fields", "nonce"], "properties": {
        "purpose": {"type": "string", "minLength": 3, "maxLength": 120},
        "fields": {"type": "array", "items": {"enum": ["username", "password", "notes", "website", "otp", "pin", "card"]}, "minItems": 1},
        "nonce": {"type": "string", "pattern": "^[A-Za-z0-9_-]{16,64}$"},
        "expires_in": {"type": "integer", "minimum": 60, "maximum": 600}}},
      "SecretRequest": {"type": "object", "properties": {
        "id": {"type": "string", "format": "uuid"}, "status": {"enum": ["pending", "approved", "delivered", "denied", "expired", "revoked"]},
        "purpose": {"type": "string"}, "fields": {"type": "array", "items": {"type": "string"}},
        "duration": {"type": ["string", "null"], "enum": ["once", "10m", "until_revoked", null]},
        "expires_at": {"type": "string"}, "decided_at": {"type": ["string", "null"]},
        "response": {"$ref": "#/components/schemas/EncryptedResponse"}}},
      "EncryptedResponse": {"type": "object", "description": "Present only when approved. Decrypt with your X25519 private key as documented; the server cannot read it.", "properties": {
        "v": {"const": 1}, "ciphertext": {"type": "string"}, "nonce": {"type": "string"}, "wrapped_key": {"type": "string"}, "signature": {"type": "string"},
        "device": {"type": "object"}}}
    }
  },
  "x-webhooks": {
    "events": ["secret_request.approved", "secret_request.denied", "secret_request.revoked"],
    "signature": "PM-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>",
    "payload": {"id": "evt_…", "type": "secret_request.approved", "created": 0, "data": {"secret_request_id": "uuid", "status": "approved"}}
  }
}
