Invite Users

Programmatically invite users to your Odeus workspace via email

⚠️ Using our API via a dedicated deployment? Just replace api.odeus.ai with your deployment's base URL: <deployment-url>/api/public

This endpoint lets you programmatically invite one or more users to your workspace. It's useful for automating onboarding flows, partner integrations, or bulk provisioning.

Prerequisites

• API Key with the USER_MANAGEMENT_API scope
• The API key must be created by a workspace admin

Behavior

• Already a member? Silently skipped.
• Has a pending join request? Automatically approved.
• Invalid email domain? Reported in invalidEmails but doesn't fail the request.
• If SAML is not enabled for the workspace, the invitation email includes a magic link for passwordless sign-in.

A 200 response can still contain invalidEmails — these are emails that passed format validation but failed deeper checks (e.g., unreachable domain). Always check both successfulInvites and invalidEmails in the response.

Odeus intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.

OpenAPI

openapi: 3.0.0
info:
  title: Odeus API
  version: 3.0.0
servers:
  - url: https://api.odeus.ai
security:
  - bearerAuth: []
paths:
  /user-management/v1/invite:
    post:
      tags:
        - User Management
      summary: Invite users to workspace
      description: >
        Sends workspace invitations to one or more users by email. Each user can
        optionally

        be assigned a specific role. If no role is specified, the default role
        `member` is used.

        Users who are already members of the workspace are silently skipped.
        Users with pending

        join requests are automatically approved. Invalid email addresses are
        reported in the

        response but do not cause the entire request to fail.

        An invitation email is sent to each successfully invited user. If the
        workspace does not

        have SAML enabled, the email includes a magic link for passwordless
        sign-in.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteUsersRequest'
            examples:
              single_user:
                summary: Invite a single user
                value:
                  users:
                    - email: [email protected]
              multiple_users_with_roles:
                summary: Invite multiple users with roles
                value:
                  users:
                    - email: [email protected]
                      role: admin
                    - email: [email protected]
                      role: member
                    - email: [email protected]
      responses:
        '200':
          description: Invitations processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteUsersResponse'
              examples:
                all_successful:
                  summary: All invitations sent
                  value:
                    status: success
                    message: Invitations processed
                    successfulInvites:
                      - [email protected]
                      - [email protected]
                    invalidEmails: []
                partial_success:
                  summary: Some emails were invalid
                  value:
                    status: success
                    message: Invitations processed
                    successfulInvites:
                      - [email protected]
                    invalidEmails:
                      - not-a-valid-email
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteUsersError'
              examples:
                missing_users:
                  summary: Missing or empty users array
                  value:
                    message: Invalid request body
                    errors:
                      - code: too_small
                        minimum: 1
                        type: array
                        inclusive: true
                        exact: false
                        message: Array must contain at least 1 element(s)
                        path:
                          - users
                invalid_role:
                  summary: Invalid role value
                  value:
                    message: Invalid request body
                    errors:
                      - code: invalid_enum_value
                        options:
                          - member
                          - editor
                          - admin
                        received: superadmin
                        message: >-
                          Invalid enum value. Expected 'member' | 'editor' |
                          'admin', received 'superadmin'
                        path:
                          - users
                          - 0
                          - role
        '401':
          description: >-
            Unauthorized - API key is missing, invalid, or the key creator was
            not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteUsersError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteUsersError'
components:
  schemas:
    InviteUsersRequest:
      type: object
      required:
        - users
      properties:
        users:
          type: array
          minItems: 1
          description: List of users to invite. At least one user is required.
          items:
            type: object
            required:
              - email
            properties:
              email:
                type: string
                format: email
                description: Email address of the user to invite
                example: [email protected]
              role:
                type: string
                enum:
                  - member
                  - editor
                  - admin
                description: Role to assign. If omitted, defaults to `member`.
                example: member
    InviteUsersResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - success
          description: Always "success" when the request is processed
          example: success
        message:
          type: string
          description: Human-readable summary of the result
          example: Invitations processed
        successfulInvites:
          type: array
          items:
            type: string
            format: email
          description: Email addresses that were successfully invited
          example:
            - [email protected]
            - [email protected]
        invalidEmails:
          type: array
          items:
            type: string
          description: >-
            Email addresses that failed deeper validation (e.g., unreachable
            domain)
          example: []
      required:
        - status
        - message
        - successfulInvites
        - invalidEmails
    InviteUsersError:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: Invalid request body
        errors:
          type: array
          items:
            type: object
          description: Detailed validation errors (present on 400 responses)
        error:
          type: string
          description: Additional error details (present on 500 responses)
      required:
        - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"