> ## Documentation Index > Fetch the complete documentation index at: https://docs.simplepay.mx/llms.txt > Use this file to discover all available pages before exploring further. # Create an API key using a SimplePay customer session > API-only first-key bootstrap. Requires a verified customer bearer with active tenant/environment membership and admin RBAC; API keys and first-party assertions cannot call this route. Obtain x-sp-step-up-token from /v1/auth/step-up/* with action api_key.create, scope api_keys:write, the same tenant/idempotency selectors, and params_hash = lowercase SHA-256 of canonical stable JSON {description,environment,scopes}. Use the trimmed description or API key default, tenant_environment as environment, sorted unique scopes, recursively sorted object keys, UTF-8, and no whitespace. ## OpenAPI ````yaml /en/openapi.json post /v1/api-keys openapi: 3.1.0 info: title: SimplePay API version: '2026-06-13' description: >- Contrato público para integrar SimplePay desde un backend. Incluye únicamente operaciones para comercios y administración protegida de credenciales. servers: - description: Live url: https://api.simplepay.mx - description: Sandbox url: https://api.test.simplepay.mx security: - SimplePayApiKey: [] tags: - name: API keys - name: Hosted Checkout - name: Payment Links - name: Payments - name: Refunds - name: Webhooks - name: Digital Catalog - name: Payment Policy - name: Reporting - name: Workspace - name: Customer Hub - name: Bookable Payments - name: Table Pay - name: Physical Checkout - name: In-person Payments - name: Terminal - name: Tap to Pay - name: Ticketing - name: Admission Control - name: Intelligence externalDocs: description: SimplePay developer documentation url: https://docs.simplepay.mx paths: /v1/api-keys: post: tags: - API keys summary: Create an API key using a SimplePay customer session description: >- API-only first-key bootstrap. Requires a verified customer bearer with active tenant/environment membership and admin RBAC; API keys and first-party assertions cannot call this route. Obtain x-sp-step-up-token from /v1/auth/step-up/* with action api_key.create, scope api_keys:write, the same tenant/idempotency selectors, and params_hash = lowercase SHA-256 of canonical stable JSON {description,environment,scopes}. Use the trimmed description or API key default, tenant_environment as environment, sorted unique scopes, recursively sorted object keys, UTF-8, and no whitespace. operationId: createApiKey parameters: - $ref: '#/components/parameters/StepUpToken' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - scopes - tenant_environment - tenant_id properties: description: type: string maxLength: 120 tenant_environment: type: string enum: - sandbox - live tenant_id: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$ scopes: type: array minItems: 1 maxItems: 64 uniqueItems: true items: type: string minLength: 3 maxLength: 96 enum: - bookable_payments:read - bookable_payments:write - admission_control:manage - admission_control:redeem - customer_hub.contacts:write - customer_hub.notes:write - customer_hub.provider_sync:write - customer_hub.segments:read - customer_hub.segments:write - customer_hub:read - customer_hub:write - digital_catalog.inventory:read - digital_catalog.inventory:write - digital_catalog:read - digital_catalog:write - hosted_checkout:read - hosted_checkout:write - intelligence:read - payment_links:read - payment_links:write - physical_checkout:read - physical_checkout:write - table_pay:read - table_pay:write - policies:read - refunds:read - refunds:write - reporting:read - tap_to_pay:read - tap_to_pay:write - terminal:read - terminal:write - ticketing:read - ticketing:write - transfers:read - transfers:write - webhooks:read - webhooks:write - workspace:read - workspace:write responses: '201': description: >- API key created. one_time_value is returned once and is never persisted by SimplePay. content: application/json: schema: $ref: '#/components/schemas/ApiKeyCreateResponse' security: - SimplePayCustomerBearer: [] components: parameters: StepUpToken: name: x-sp-step-up-token in: header required: true description: >- Short-lived, single-use SimplePay recent-auth proof bound to this mutation and Idempotency-Key. schema: type: string minLength: 32 maxLength: 4096 IdempotencyKey: name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 255 schemas: ApiKeyCreateResponse: type: object additionalProperties: false required: - key - object - one_time_value properties: key: $ref: '#/components/schemas/ApiKeySummary' object: const: simplepay.v1.api_key one_time_value: type: string minLength: 16 description: >- One-time plaintext credential. Never returned by list or replay and never persisted by SimplePay. ApiKeySummary: type: object additionalProperties: false required: - created_at - created_by_email - description - environment - expires_at - id - obfuscated_value - scopes - status properties: created_at: type: - string - 'null' format: date-time created_by_email: type: - string - 'null' format: email description: type: string maxLength: 120 environment: type: string enum: - sandbox - live expires_at: type: - string - 'null' format: date-time id: type: string format: uuid obfuscated_value: type: string scopes: type: array uniqueItems: true items: type: string status: type: string enum: - active - failed - provisioning - revoked - revoking - rotating securitySchemes: SimplePayApiKey: type: http scheme: bearer SimplePayCustomerBearer: type: http scheme: bearer description: SimplePay customer session bearer. Never a tenant API credential. ````