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

# Provision a customer

> Creates the customer's account and a workspace of their own, or refreshes a customer you provisioned before. Safe to repeat. An e-mail that already belongs to someone else is never taken over: it is a `409` with an `error_code`, and nothing is written. See [Single sign-on](/partner/single-sign-on#1-provision-the-customer).



## OpenAPI

````yaml /api-reference/partner.openapi.json post /partner/users
openapi: 3.1.0
info:
  title: Partner API
  version: 1.0.0
  description: >-
    Provision your customers, sign them in with single sign-on, issue their
    workspace API keys and connect their messaging channels. Authenticated by
    your partner key as `X-API-KEY`, from your backend only.
servers:
  - url: https://app.onlysocial.io/api
    description: OnlySocial
security:
  - partnerKey: []
tags:
  - name: Customers
    description: Create or refresh a customer's account and workspace.
  - name: Single sign-on
    description: Swap a token signed with your SSO secret for a one-time sign-in link.
  - name: Workspace API keys
    description: Issue, list and revoke the `osk_` keys of a workspace you provisioned.
  - name: Channel Connect
    description: Hosted links that connect a customer's own messaging channels.
paths:
  /partner/users:
    post:
      tags:
        - Customers
      summary: Provision a customer
      description: >-
        Creates the customer's account and a workspace of their own, or
        refreshes a customer you provisioned before. Safe to repeat. An e-mail
        that already belongs to someone else is never taken over: it is a `409`
        with an `error_code`, and nothing is written. See [Single
        sign-on](/partner/single-sign-on#1-provision-the-customer).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - external_id
                - email
              properties:
                external_id:
                  type: string
                  maxLength: 255
                  description: >-
                    Your own id for the customer. Use something that never
                    changes.
                  example: dealer-4821
                email:
                  type: string
                  format: email
                  maxLength: 255
                  example: sales@acmemotors.test
                name:
                  type: string
                  maxLength: 255
                  example: Acme Motors
      responses:
        '200':
          description: Provisioned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: User provisioned successfully.
                  data:
                    $ref: '#/components/schemas/ProvisionResult'
        '400':
          $ref: '#/components/responses/Refused'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    ProvisionResult:
      type: object
      properties:
        user_id:
          type: integer
          example: 184
        external_id:
          type: string
          example: dealer-4821
        email:
          type: string
          example: sales@acmemotors.test
        name:
          type: string
          example: Acme Motors
        created_at:
          type: string
          format: date-time
          example: '2026-10-20T09:12:04+00:00'
        workspace_id:
          type:
            - string
            - 'null'
          format: uuid
          example: 6b1f0e2c-…
        workspace_ids:
          type: array
          items:
            type: string
            format: uuid
        outcome:
          type: string
          enum:
            - created
            - updated
          example: created
        workspace_created:
          type: boolean
          example: true
        warnings:
          type: array
          items:
            type: string
            enum:
              - existing_account_linked_without_workspace
          example: []
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
        error_code:
          type: string
  responses:
    Refused:
      description: Refused, for example an e-mail outside your allowed domains.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: Email domain not allowed for this partner.
    Unauthenticated:
      description: Missing or invalid partner key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: Invalid or inactive API key.
    Conflict:
      description: The e-mail belongs to someone else. Nothing was written.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  error_code:
                    type: string
                    enum:
                      - email_has_existing_account
                      - email_belongs_to_another_partner
                      - email_in_use_by_another_account
          example:
            success: false
            message: That email address is already in use.
            error_code: email_has_existing_account
    ValidationFailed:
      description: A field failed validation.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Validation failed.
              errors:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
    TooManyRequests:
      description: Rate limited. Wait for `Retry-After` seconds.
  securitySchemes:
    partnerKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Your partner API key, `pk_…`. Backend only.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.