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

# Create an API key

> Creates an API key for the authenticated account. Restrict access by listing permitted IP addresses in `permitted_ips`.



## OpenAPI

````yaml https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/api-keys
openapi: 3.1.0
info:
  title: Wavix APIs
  description: >-
    Wavix provides robust APIs that let you integrate voice and text messaging
    features directly into your app. Send text, place calls, and access detailed
    reports  programmatically.
  termsOfService: https://wavix.com/terms-and-conditions
  license:
    name: MIT
    identifier: MIT
  contact:
    name: Wavix
    url: https://wavix.com
    email: support@wavix.com
  version: '1.0'
servers:
  - url: https://api.wavix.com
    description: https://api.wavix.com
    variables: {}
security:
  - bearerAuth: []
tags:
  - name: SIP trunks
    description: SIP trunks
  - name: Buy
    description: Numbers
  - name: Cart
    description: Numbers
  - name: My numbers
    description: Numbers
  - name: Billing
    description: Billing, transactions, and invoices
  - name: Profile
    description: Account profile and customer information
  - name: CDRs
    description: Call detail records and call history
  - name: Speech Analytics
    description: Call transcription and speech analytics
  - name: SMS and MMS
    description: Messaging
  - name: Number Validator
    description: Phone number validation
  - name: Link shortener
    description: Short link and click metrics
  - name: 2FA
    description: Two-factor authentication
  - name: 10DLC
    description: 10DLC Campaigns and Brands
  - name: API Keys
    description: API key management
  - name: Call webhooks
    description: Webhook configuration for call events
  - name: Call control
    description: Programmable Voice
  - name: Call streaming
    description: Real-time call audio streaming over WebSocket
  - name: Call recording
    description: Call recording
  - name: Sub-accounts
    description: Sub-account management
  - name: Voice campaigns
    description: Outbound voice campaigns
  - name: Wavix Embeddable
    description: WebRTC embeddable widget
paths:
  /v1/api-keys:
    post:
      tags:
        - API Keys
      summary: Create an API key
      description: >-
        Creates an API key for the authenticated account. Restrict access by
        listing permitted IP addresses in `permitted_ips`.
      operationId: api_keys_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyCreateRequest'
            example:
              label: Production API Key
              active: true
              restricted: true
              permitted_ips:
                - 192.168.1.1
                - 10.0.0.1
              scopes_enabled: true
              numbers:
                allow: read
              calls:
                allow: read
              messages:
                allow: write
              two_fa:
                allow: write
              billing:
                allow: read
      responses:
        '200':
          description: Returns the created API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
              examples:
                default:
                  value:
                    id: 123
                    label: Production API Key
                    value: abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
                    active: true
                    restricted: true
                    permitted_ips:
                      - 192.168.1.1
                      - 10.0.0.1
                    scopes_enabled: true
                    last_used_at: null
                    numbers:
                      allow: read
                    trunks:
                      allow: none
                    calls:
                      allow: read
                    messages:
                      allow: write
                    recordings:
                      allow: none
                    campaigns:
                      allow: none
                    two_fa:
                      allow: write
                    validator:
                      allow: none
                    webhooks:
                      allow: none
                    embeddable:
                      allow: none
                    billing:
                      allow: read
                    account:
                      allow: none
                    subaccounts:
                      allow: none
                    created_at: '2024-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '422':
          description: Returns a validation error when a field value is invalid.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                ip_invalid:
                  summary: Invalid IP address
                  value:
                    success: false
                    message: Ip has incorrect format
                scope_not_hash:
                  summary: Scope value is not an object
                  value:
                    success: false
                    message: 'API key scope numbers: must be a hash'
                scope_extra_keys:
                  summary: Scope object has unexpected keys
                  value:
                    success: false
                    message: 'API key scope numbers: must have only "allow" key'
                scope_invalid_allow:
                  summary: Unsupported allow value
                  value:
                    success: false
                    message: >-
                      API key scope numbers: allow must be one of: none, read,
                      write
components:
  schemas:
    ApiKeyCreateRequest:
      type: object
      required:
        - label
      properties:
        label:
          type: string
          description: API key label.
          example: My API key
        active:
          type: boolean
          description: Indicates whether the API key should be activated upon creation.
          default: true
          example: true
        restricted:
          type: boolean
          description: >-
            Indicates whether to restrict API key access by IP address. When
            enabled, only requests from IP addresses listed in `permitted_ips`
            are allowed.
          default: false
          example: true
        permitted_ips:
          type: array
          items:
            type: string
          description: >-
            List of permitted IP addresses for this API key. Each must be a
            valid IPv4 address. Required when `restricted` is true.
          example:
            - 192.168.1.1
            - 10.0.0.1
        scopes_enabled:
          type: boolean
          description: >-
            When `true`, scope fields below are enforced. When `false`
            (default), the

            key has full access. Omitted scope fields default to `{ allow: none
            }`,

            so with `scopes_enabled: true` and no scopes set the key has no
            access.
          default: false
          example: true
        numbers:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
          description: >-
            View, buy, release, and configure phone numbers, browse inventory,
            and manage the cart.
        trunks:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
          description: View, create, update, and delete SIP trunks and their settings.
        calls:
          allOf:
            - $ref: '#/components/schemas/ApiKeyCallsScopePermission'
          description: >-
            Access call records and active calls, and control live call actions
            such as starting, answering, ending, audio playback, DTMF,
            streaming, and transcription requests.
        messages:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
          description: >-
            Access message history and Sender IDs, send messages, manage
            opt-outs, and create or delete Sender IDs.
        recordings:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
          description: List, download, and delete call recordings.
        campaigns:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
          description: >-
            View campaign analytics and Sender ID or Brand status, schedule bulk
            voice or SMS campaigns, register Brands, and create short links.
        two_fa:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
          description: >-
            View 2FA service details and verification logs, trigger OTPs by
            voice or SMS, and validate verification codes.
        validator:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
          description: >-
            View number validation results and trigger single or bulk validation
            or HLR lookup requests.
        webhooks:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
          description: List, create, and delete webhooks.
        embeddable:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
          description: >-
            Manage widget tokens, including listing, viewing, creating,
            updating, and deleting them.
        billing:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
          description: >-
            Access statements, balance, payment methods, usage reports, and
            billing settings, including payment method updates.
        account:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
          description: View and update account profile information and timezone.
        subaccounts:
          allOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
          description: >-
            Manage subaccounts: list and view them, create, update, and suspend
            them.
    ApiKey:
      type: object
      description: API key details including IP restrictions and scope permissions.
      required:
        - id
        - label
        - value
        - active
        - restricted
        - permitted_ips
        - scopes_enabled
        - last_used_at
        - numbers
        - trunks
        - calls
        - messages
        - recordings
        - campaigns
        - two_fa
        - validator
        - webhooks
        - embeddable
        - billing
        - account
        - subaccounts
        - created_at
      properties:
        id:
          type: integer
          description: API key ID.
          example: 123
        label:
          type: string
          description: API key label.
          example: Production API Key
        value:
          type: string
          description: API key value.
          example: abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
        active:
          type: boolean
          description: Indicates whether the API key is active.
          example: true
        restricted:
          type: boolean
          description: |-
            Indicates whether IP restrictions are enabled. When enabled,
             the API key works only from IP addresses in `permitted_ips`.
          example: true
        permitted_ips:
          type: array
          items:
            type: string
          description: |-
            List of permitted IP addresses. If `restricted` is false,
             an empty list means no IP restrictions. If `restricted` is true,
              an empty list prevents all requests.
          example:
            - 192.168.1.1
            - 10.0.0.1
        scopes_enabled:
          type: boolean
          description: |-
            When `true`, the key is restricted to the permissions defined in the
            scope fields below. When `false`, the key has full access.
          example: true
        last_used_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Timestamp of the most recent authenticated request made with this
            key.
          example: '2026-04-20T15:42:11Z'
        numbers:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
            - type: 'null'
          description: >-
            View, buy, release, and configure phone numbers, browse inventory,
            and manage the cart.
        trunks:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
            - type: 'null'
          description: View, create, update, and delete SIP trunks and their settings.
        calls:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyCallsScopePermission'
            - type: 'null'
          description: >-
            Access call records and active calls, and control live call actions
            such as starting, answering, ending, audio playback, DTMF,
            streaming, and transcription requests.
        messages:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
            - type: 'null'
          description: >-
            Access message history and Sender IDs, send messages, manage
            opt-outs, and create or delete Sender IDs.
        recordings:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
            - type: 'null'
          description: List, download, and delete call recordings.
        campaigns:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
            - type: 'null'
          description: >-
            View campaign analytics and Sender ID or Brand status, schedule bulk
            voice or SMS campaigns, register Brands, and create short links.
        two_fa:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
            - type: 'null'
          description: >-
            View 2FA service details and verification logs, trigger OTPs by
            voice or SMS, and validate verification codes.
        validator:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
            - type: 'null'
          description: >-
            View number validation results and trigger single or bulk validation
            or HLR lookup requests.
        webhooks:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
            - type: 'null'
          description: List, create, and delete webhooks.
        embeddable:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
            - type: 'null'
          description: >-
            Manage widget tokens, including listing, viewing, creating,
            updating, and deleting them.
        billing:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
            - type: 'null'
          description: >-
            Access statements, balance, payment methods, usage reports, and
            billing settings, including payment method updates.
        account:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
            - type: 'null'
          description: View and update account profile information and timezone.
        subaccounts:
          anyOf:
            - $ref: '#/components/schemas/ApiKeyScopePermission'
            - type: 'null'
          description: >-
            Manage subaccounts: list and view them, create, update, and suspend
            them.
        created_at:
          type: string
          format: date-time
          description: Creation date and time in ISO 8601 format.
          example: '2024-01-15T10:30:00Z'
    ValidationErrorResponse:
      title: ValidationErrorResponse
      type: object
      properties:
        success:
          type: boolean
          description: >-
            Indicates whether the request was successful. Always `false` for
            this error.
          example: false
        message:
          type: string
          description: >-
            Human-readable description naming the missing or invalid request
            parameter.
          example: Missing or invalid parameter <param_name>
    ApiKeyScopePermission:
      type: object
      description: Permission level for an API key scope group.
      properties:
        allow:
          type: string
          enum:
            - none
            - read
            - write
          default: none
          description: |-
            Permission level:
            - `none`: no access
            - `read`: GET only
            - `write`: all methods (includes read)
          example: read
    ApiKeyCallsScopePermission:
      type: object
      description: Permission level for the `calls` scope group.
      properties:
        allow:
          type: string
          enum:
            - none
            - read
            - write
          default: none
          description: |-
            Permission level:
            - `none`: no access
            - `read`: GET requests, `POST /v1/cdrs`
            - `write`: all methods (includes read)
          example: read
    UnauthorizedErrorResponse:
      title: UnauthorizedErrorResponse
      type: object
      properties:
        success:
          type: boolean
          description: >-
            Indicates whether the request was successful. Always `false` for
            this error.
          example: false
        error:
          type: boolean
          description: >-
            Indicates that the response represents an error. Always `true` for
            this error.
          example: true
        message:
          type: string
          description: >-
            Human-readable description stating that authentication is missing or
            invalid.
          example: Unauthorized
    ForbiddenErrorResponse:
      title: ForbiddenErrorResponse
      type: object
      properties:
        success:
          type: boolean
          description: >-
            Indicates whether the request was successful. Always `false` for
            this error.
          example: false
        message:
          type: string
          description: Human-readable description of why access is forbidden.
          example: The service is not provisioned for your account.
  responses:
    BadRequestErrorResponse:
      description: Request failed. Missing or invalid parameter <param_name>
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
    UnauthorizedErrorResponse:
      description: Unauthorized
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedErrorResponse'
    ForbiddenErrorResponse:
      description: Request failed. The feature is disabled for your account.
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Wavix API key. Pass as `Authorization: Bearer <api_key>`. Keys support
        per-resource scopes (none / read / write). See [Restricted keys and
        scopes](https://docs.wavix.com/api-reference/authentication#restricted-keys-and-scopes).

````