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

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugin-types/ pages for correct interfaces and manifests.

# Generate API Key

> Generates a new API key for the active brand. Displays the generated plain key exactly once.
**Requires special admin authorization**: API key must possess `write` and `admin` scopes, and the `X-Super-Admin-Email` header
must identify an active superadmin user.




## OpenAPI

````yaml /api/merchant_api.yaml post /api-keys
openapi: 3.1.0
info:
  title: OwnPay Merchant API
  description: >
    The OwnPay Merchant API enables merchants to programmatically interface with
    their white-labeled payment gateway.

    It exposes endpoints to initiate payments (creating payment intents), query
    transaction statuses, issue full or partial refunds, manage customer
    profiles securely in compliance with GDPR and OWASP, generate and revoke API
    keys, and test/audit webhook delivery attempts.


    ### Authentication

    Authentication is performed via HTTP Bearer token in the `Authorization`
    header.

    ```http

    Authorization: Bearer your_api_key_here

    ```

    API keys carry specific privilege scopes (e.g., `read`, `write`, `admin`).

    Some administrative operations (like listing/generating API keys) require
    **both** `write` and `admin` scopes, as well as passing a valid platform
    super-administrator's email address in the `X-Super-Admin-Email` header for
    safety.
  version: 1.0.0
servers:
  - url: https://{brand_domain}/api/v1
    description: Sandbox or Production white-labeled brand gateway API server.
    variables:
      brand_domain:
        default: ownpay.org
        description: The custom domain configured for your white-labeled brand.
security:
  - BearerAuth: []
paths:
  /api-keys:
    post:
      summary: Generate API Key
      description: >
        Generates a new API key for the active brand. Displays the generated
        plain key exactly once.

        **Requires special admin authorization**: API key must possess `write`
        and `admin` scopes, and the `X-Super-Admin-Email` header

        must identify an active superadmin user.
      operationId: generateApiKey
      parameters:
        - name: X-Super-Admin-Email
          in: header
          required: true
          description: Email of an active platform super-administrator.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateApiKeyRequest'
      responses:
        '201':
          description: >-
            API key generated successfully. Plain key secret is returned in the
            response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateApiKeyResponse'
        '400':
          description: Missing superadmin email header.
        '403':
          description: Insufficient privileges.
        '422':
          description: Invalid key scopes requested.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorsResponse'
components:
  schemas:
    GenerateApiKeyRequest:
      type: object
      properties:
        name:
          type: string
          description: Friendly identifier label for the key.
          example: POS-System-Integration
        scopes:
          type: array
          items:
            type: string
            enum:
              - read
              - write
              - admin
          default:
            - read
            - write
          example:
            - read
            - write
    GenerateApiKeyResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            key:
              type: string
              description: >-
                The full generated API key secret. You must copy and store this;
                it is never visible again.
              example: op_live_5gH2k8S3m9F0a1D2...
            prefix:
              type: string
              description: Safe prefix string used to identify the key in reports.
              example: op_live_5gH2
            warning:
              type: string
              example: Store this key securely. It cannot be retrieved again.
    ApiErrorsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: amount must be a positive number
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: INVALID_AMOUNT
              message:
                type: string
                example: amount must be a positive number
              field:
                type: string
                example: amount
        request_id:
          type: string
          example: 8f5a2e9b0c7d4e5f
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Provide the Bearer API Key generated for your brand.

````

## Related topics

- [Developer Quickstart - Build Your First Payment Integration](/docs/developer/quickstart.md)
- [List API Keys](/docs/api-reference/list-api-keys.md)
- [Revoke API Key](/docs/api-reference/revoke-api-key.md)
- [Node.js SDK - TypeScript-First Payment Integration](/docs/developer/integration/nodejs.md)
- [OwnPay API Overview - REST API for Multi-Brand Payments](/docs/api/overview.md)