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

# Create Organization Invitation

> Create an email-bound organization invitation and return its shareable URL once.

Required permission: `members.manage`.



## OpenAPI

````yaml /lib/api-spec/openapi.yaml post /api/v1/organizations/{org_id}/invitations
openapi: 3.1.0
info:
  title: airmux Control Plane API
  description: >
    Manage airmux organizations, workspaces, management keys, provider
    credentials, and data-plane synchronization.


    Organization and workspace targets are part of each URL. Successful
    responses wrap their result in

    `{"data": ...}`. Authenticate with a control-plane management key or a
    browser session as documented by

    each operation. Inference keys authenticate model requests at the data plane
    and are not accepted here.
  version: 0.1.0
servers: []
security: []
tags:
  - name: Auth
    description: Sign in human users, manage browser sessions, and authorize the CLI
    x-displayName: Authentication
  - name: Enrollment
    description: List a user's organizations and create their personal organization
  - name: Instance Organizations
    description: List and create organizations on this airmux instance
    x-displayName: Organizations
  - name: Instance Users
    description: Manage human users and service accounts across the instance
    x-displayName: Users
  - name: Instance Management Keys
    description: >-
      List management keys across the instance, issue instance-scoped
      credentials, and revoke keys
    x-displayName: Management Keys
  - name: Instance Model Catalog
    description: Manage the providers and models available through this airmux instance
    x-displayName: Model Catalog
  - name: Instance Provider Credentials
    description: Manage provider API keys available across the airmux instance
    x-displayName: Provider Credentials
  - name: Data Plane Instances
    description: Inspect connected data-plane instances
    x-displayName: Data Planes
  - name: Instance Activity
    description: Inspect recent audited changes across the instance
    x-displayName: Activity
  - name: OSS
    description: Bootstrap a new self-hosted airmux deployment
    x-displayName: Self-hosting
  - name: Organization Settings
    description: View, update, and delete one organization
    x-displayName: Settings
  - name: Organization Members
    description: Manage organization membership and organization roles
    x-displayName: Members
  - name: Organization Service Accounts
    description: >-
      Create and delete organization-managed machine principals and their
      initial management credentials
    x-displayName: Service Accounts
  - name: Organization Invitations
    description: Invite human users to an organization and optionally one workspace
    x-displayName: Invitations
  - name: Organization Workspaces
    description: List and create workspaces within an organization
    x-displayName: Workspaces
  - name: Organization Management Keys
    description: >-
      List management keys within an organization, issue organization-scoped
      credentials, and revoke keys
    x-displayName: Management Keys
  - name: Organization Provider Credentials
    description: Manage provider API keys available across an organization
    x-displayName: Provider Credentials
  - name: Organization Usage Events
    description: Inspect usage events across an organization
    x-displayName: Usage Events
  - name: Organization Reports
    description: Explore usage and requests across an organization or one workspace
    x-displayName: Reports
  - name: Organization Activity
    description: Inspect recent audited changes in an organization
    x-displayName: Activity
  - name: Organization Model Catalog
    description: Inspect the provider and model catalog available to an organization
    x-displayName: Model Catalog
  - name: Workspace Settings
    description: View, update, and delete one workspace
    x-displayName: Settings
  - name: Workspace Policies
    description: Manage workspace inference restrictions and fallbacks
    x-displayName: Policies
  - name: Workspace Members
    description: Manage workspace membership and workspace roles
    x-displayName: Members
  - name: Workspace Management Keys
    description: List and issue management keys scoped to a workspace and revoke keys
    x-displayName: Management Keys
  - name: Workspace Playground
    description: Create and end short-lived browser sessions for playground model requests
    x-displayName: Playground
  - name: Workspace Inference Keys
    description: Issue and revoke credentials for model requests to a workspace
    x-displayName: Inference Keys
  - name: Workspace Provider Credentials
    description: Manage provider API keys available to one workspace
    x-displayName: Provider Credentials
  - name: Workspace Usage Events
    description: Inspect usage events for one workspace
    x-displayName: Usage Events
  - name: Workspace Model Catalog
    description: Inspect the provider and model catalog available to a workspace
    x-displayName: Model Catalog
  - name: Data Plane API
    description: Poll bundles, ingest usage events, and record data-plane heartbeats
    x-displayName: Synchronization
paths:
  /api/v1/organizations/{org_id}/invitations:
    post:
      tags:
        - Organization Invitations
      summary: Create Organization Invitation
      description: >-
        Create an email-bound organization invitation and return its shareable
        URL once.


        Required permission: `members.manage`.
      operationId: create_invitation
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            title: Org Id
          description: Organization ID or slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgInvitationCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope_OrgInvitationMintedOut_'
        '401':
          description: Authentication failed
        '403':
          description: The credential does not have the required permission
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - ManagementKey: []
        - SessionCookie: []
components:
  schemas:
    OrgInvitationCreate:
      properties:
        email:
          type: string
          maxLength: 320
          minLength: 3
          title: Email
          description: Email address that must match the account accepting the invitation
        org_role:
          type: string
          pattern: ^(admin|member)$
          title: Org Role
          description: Organization role to grant
        workspace_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Workspace Id
          description: Optional workspace to join
        workspace_role:
          anyOf:
            - type: string
              pattern: ^(admin|member|viewer)$
            - type: 'null'
          title: Workspace Role
          description: Role to grant in the selected workspace
      additionalProperties: false
      type: object
      required:
        - email
        - org_role
      title: OrgInvitationCreate
    Envelope_OrgInvitationMintedOut_:
      properties:
        data:
          $ref: '#/components/schemas/OrgInvitationMintedOut'
      type: object
      required:
        - data
      title: Envelope[OrgInvitationMintedOut]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    OrgInvitationMintedOut:
      properties:
        invitation:
          $ref: '#/components/schemas/OrgInvitationOut'
        url:
          type: string
          title: Url
      type: object
      required:
        - invitation
        - url
      title: OrgInvitationMintedOut
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    OrgInvitationOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        org_id:
          type: string
          format: uuid
          title: Org Id
        email:
          type: string
          title: Email
        org_role:
          type: string
          title: Org Role
        workspace_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Workspace Id
        workspace_role:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Role
        created_by_user_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Created By User Id
        expires_at:
          type: string
          format: date-time
          title: Expires At
        accepted_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Accepted At
        accepted_by_user_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Accepted By User Id
        revoked_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Revoked At
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        status:
          type: string
          enum:
            - pending
            - expired
            - accepted
            - revoked
          title: Status
      type: object
      required:
        - id
        - org_id
        - email
        - org_role
        - workspace_id
        - workspace_role
        - created_by_user_id
        - expires_at
        - accepted_at
        - accepted_by_user_id
        - revoked_at
        - created_at
        - updated_at
        - status
      title: OrgInvitationOut
  securitySchemes:
    ManagementKey:
      type: http
      description: >-
        A control-plane management key using the `sk-cp-` prefix. Inference keys
        are not accepted by control-plane endpoints.
      scheme: bearer
    SessionCookie:
      type: apiKey
      in: cookie
      name: airmux_session
      description: >-
        Browser session cookie returned by login or signup. Browser requests
        must also send `X-Requested-With`.

````