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

# Provision an organization

> Creates a new kelviq user + organization on behalf of the partner, issues API keys, and emails the user a link to set their password. Fails with `409` if `email` belongs to an existing kelviq user, or with `400` if `externalId` already exists for this partner.



## OpenAPI

````yaml /api-reference/openapi.json post /partner/organizations/
openapi: 3.0.0
info:
  title: kelviq API
  version: 1.0.0
  description: >-
    API for interacting with kelviq services, derived from Python SDK
    documentation.
servers:
  - url: https://api.kelviq.com/api/v1
    description: kelviq API Server (General - specific operations might override)
security:
  - bearerAuth: []
tags:
  - name: Products
    description: Catalog products.
  - name: Product Settings
    description: Per-product settings (currency, VPN/Tor/proxy, product URL).
  - name: Product Files
    description: Product images and downloadable assets.
  - name: Features
    description: Catalog features that can be granted as plan entitlements.
  - name: Plans
    description: Catalog plans (CRUD, publish, versions, prices).
  - name: Plan Entitlements
    description: Feature entitlements attached to a plan.
  - name: Plan Files
    description: Files attached to plans, and signed download links.
  - name: Media
    description: Generate presigned S3 upload URLs for product/plan images and files.
  - name: Partner
    description: Partner integration APIs (organization provisioning, lookup).
  - name: Charges
    description: >-
      One-time payments charged immediately against a customer's default payment
      method.
paths:
  /partner/organizations/:
    post:
      tags:
        - Partner
      summary: Provision an organization
      description: >-
        Creates a new kelviq user + organization on behalf of the partner,
        issues API keys, and emails the user a link to set their password. Fails
        with `409` if `email` belongs to an existing kelviq user, or with `400`
        if `externalId` already exists for this partner.
      operationId: provisionPartnerOrganization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerOrganizationProvisionRequest'
      responses:
        '201':
          description: Organization provisioned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerOrganization'
              example:
                userId: 4271
                organizationIdentifier: 8e1d7b1a-6c4d-4e3a-9b2d-3f6e4c2b1ad0
                organizationSlug: acme-corp
                clientKey: ck_live_a1b2c3d4e5f6
                serverKey: sk_live_9z8y7x6w5v4u
                partnerExternalId: acme-corp
        '400':
          description: Validation error (e.g. duplicate `externalId` for this partner).
        '401':
          description: Unauthorized — missing or invalid `X-Kelviq-Partner-Key` header.
        '409':
          description: An account with the supplied `email` already exists.
      security:
        - partnerKeyAuth: []
components:
  schemas:
    PartnerOrganizationProvisionRequest:
      type: object
      required:
        - externalId
        - email
      description: >-
        Payload to provision a new organization on behalf of a partner. The
        owner user is created (or an error is returned if the email is already
        taken), an organization is set up, API keys are issued, and a welcome /
        set-password email is sent to the user.
      properties:
        externalId:
          type: string
          maxLength: 128
          description: >-
            Partner-side identifier for this organization. Must be unique within
            the partner. Used later by `GET
            /partner/organizations/by-external-id/{externalId}/`.
          example: acme-corp
        email:
          type: string
          format: email
          description: >-
            Email address of the organization owner. Must not match any existing
            kelviq user.
          example: owner@acme.example.com
        businessName:
          type: string
          maxLength: 200
          description: >-
            Optional business name for the organization. If provided, the
            organization's name and slug are set from this value (slug is
            auto-deduplicated).
          example: Acme Corp
      example:
        externalId: acme-corp
        email: owner@acme.example.com
        businessName: Acme Corp
    PartnerOrganization:
      type: object
      description: >-
        Organization owned by a partner. Returned by all partner organization
        endpoints.
      properties:
        userId:
          type: integer
          nullable: true
          description: Internal kelviq user ID of the organization owner.
          example: 4271
        organizationIdentifier:
          type: string
          format: uuid
          description: Stable UUID identifier for the organization.
          example: 8e1d7b1a-6c4d-4e3a-9b2d-3f6e4c2b1ad0
        organizationSlug:
          type: string
          nullable: true
          description: URL-safe slug for the organization.
          example: acme-corp
        clientKey:
          type: string
          nullable: true
          description: Public client key for the organization's API integration.
          example: ck_live_a1b2c3d4e5f6
        serverKey:
          type: string
          nullable: true
          description: Private server key for the organization. Treat as a secret.
          example: sk_live_9z8y7x6w5v4u
        partnerExternalId:
          type: string
          nullable: true
          description: Partner-side identifier supplied at provisioning time.
          example: acme-corp
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        The Server API Key obtained from the kelviq application. Pass as a
        Bearer token in the Authorization header. Example: 'Authorization:
        Bearer __YOUR_API_KEY__'
    partnerKeyAuth:
      type: apiKey
      in: header
      name: X-Kelviq-Partner-Key
      description: >-
        Partner integration secret issued by kelviq. Send the raw secret
        (prefixed `kvqp_`) in the `X-Kelviq-Partner-Key` header on every partner
        API request.

````