openapi: 3.1.0
info:
  title: PropelAuth Organization API
  description: |
    Backend REST API for managing tenants (organizations) in PropelAuth. Create and update
    organizations, add and remove members, invite users, change roles, manage role mappings,
    and revoke pending invites. All endpoints require a PropelAuth Backend Integration API key
    presented as a Bearer token.
  version: "1.0.0"
  contact:
    name: PropelAuth Support
    url: https://www.propelauth.com
    email: support@propelauth.com
  license:
    name: PropelAuth Terms
    url: https://www.propelauth.com/legal/terms-of-service
servers:
  - url: https://{authId}.propelauthtest.com
    description: Test environment
    variables:
      authId:
        default: "0000000000"
  - url: https://auth.example.com
    description: Production / Staging custom domain
security:
  - BackendApiKey: []
tags:
  - name: Organizations
    description: Create, read, update, and delete tenant organizations
  - name: Members
    description: Add, remove, invite, and change roles for users within an organization
  - name: Role Mappings
    description: Manage custom role mappings per organization
  - name: Invites
    description: Inspect and revoke pending organization invites
paths:
  /api/backend/v1/org/:
    post:
      summary: Create Org
      description: Create a new organization (tenant).
      operationId: createOrg
      tags: [Organizations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrgRequest'
      responses:
        '201':
          description: Org created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Org'
  /api/backend/v1/org/{orgId}:
    get:
      summary: Fetch Org
      description: Get an organization by ID.
      operationId: fetchOrg
      tags: [Organizations]
      parameters:
        - $ref: '#/components/parameters/OrgId'
      responses:
        '200':
          description: Org found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Org'
    put:
      summary: Update Org
      description: Update mutable organization fields.
      operationId: updateOrg
      tags: [Organizations]
      parameters:
        - $ref: '#/components/parameters/OrgId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrgRequest'
      responses:
        '200':
          description: Org updated
    delete:
      summary: Delete Org
      description: Permanently delete an organization.
      operationId: deleteOrg
      tags: [Organizations]
      parameters:
        - $ref: '#/components/parameters/OrgId'
      responses:
        '200':
          description: Org deleted
  /api/backend/v1/org/query:
    post:
      summary: Fetch Orgs
      description: Page through organizations with optional filters and ordering.
      operationId: fetchOrgs
      tags: [Organizations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                page_size: { type: integer, default: 10 }
                page_number: { type: integer, default: 0 }
                order_by:
                  type: string
                  enum: [CREATED_AT_ASC, CREATED_AT_DESC, NAME]
                name: { type: string, description: Filter by org name substring }
      responses:
        '200':
          description: Page of orgs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgPage'
  /api/backend/v1/user/org/{orgId}:
    get:
      summary: Fetch Users In Org
      description: List users that belong to the supplied organization.
      operationId: fetchUsersInOrg
      tags: [Members]
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - name: page_size
          in: query
          schema: { type: integer, default: 10 }
        - name: page_number
          in: query
          schema: { type: integer, default: 0 }
        - name: role
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Page of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPage'
  /api/backend/v1/org/add_user:
    post:
      summary: Add User To Org
      description: Add an existing user to an organization with a specified role.
      operationId: addUserToOrg
      tags: [Members]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_id, org_id, role]
              properties:
                user_id: { type: string, format: uuid }
                org_id: { type: string, format: uuid }
                role: { type: string }
                additional_roles:
                  type: array
                  items: { type: string }
      responses:
        '200':
          description: User added
  /api/backend/v1/invite_user:
    post:
      summary: Invite User To Org
      description: Send an invite email for a user to join an organization.
      operationId: inviteUserToOrg
      tags: [Invites]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, org_id, role]
              properties:
                email: { type: string, format: email }
                org_id: { type: string, format: uuid }
                role: { type: string }
                additional_roles:
                  type: array
                  items: { type: string }
      responses:
        '200':
          description: Invite sent
  /api/backend/v1/invite_user_by_id:
    post:
      summary: Invite User To Org By User ID
      description: Invite an existing user (by ID) into an organization.
      operationId: inviteUserToOrgById
      tags: [Invites]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_id, org_id, role]
              properties:
                user_id: { type: string, format: uuid }
                org_id: { type: string, format: uuid }
                role: { type: string }
      responses:
        '200':
          description: Invite created
  /api/backend/v1/org/change_role:
    post:
      summary: Change Role
      description: Change a user's role within an organization.
      operationId: changeRole
      tags: [Members]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_id, org_id, role]
              properties:
                user_id: { type: string, format: uuid }
                org_id: { type: string, format: uuid }
                role: { type: string }
                additional_roles:
                  type: array
                  items: { type: string }
      responses:
        '200':
          description: Role updated
  /api/backend/v1/org/remove_user:
    post:
      summary: Remove User From Org
      description: Remove a user from an organization.
      operationId: removeUserFromOrg
      tags: [Members]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_id, org_id]
              properties:
                user_id: { type: string, format: uuid }
                org_id: { type: string, format: uuid }
      responses:
        '200':
          description: User removed
  /api/backend/v1/custom_role_mappings:
    get:
      summary: Fetch Role Mappings
      description: List custom role mappings configured for your project.
      operationId: fetchRoleMappings
      tags: [Role Mappings]
      responses:
        '200':
          description: Role mappings
          content:
            application/json:
              schema:
                type: object
                properties:
                  custom_role_mappings:
                    type: array
                    items: { $ref: '#/components/schemas/RoleMapping' }
  /api/backend/v1/pending_org_invites:
    get:
      summary: Fetch Pending Invites
      description: Page through pending invites for an organization or across the whole project.
      operationId: fetchPendingInvites
      tags: [Invites]
      parameters:
        - name: org_id
          in: query
          schema: { type: string, format: uuid }
        - name: page_size
          in: query
          schema: { type: integer, default: 10 }
        - name: page_number
          in: query
          schema: { type: integer, default: 0 }
      responses:
        '200':
          description: Pending invites
          content:
            application/json:
              schema:
                type: object
                properties:
                  invites:
                    type: array
                    items: { $ref: '#/components/schemas/PendingInvite' }
                  total_invites: { type: integer }
                  has_more_results: { type: boolean }
    delete:
      summary: Revoke Pending Org Invite
      description: Revoke a pending invite.
      operationId: revokePendingOrgInvite
      tags: [Invites]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [org_id, invitee_email]
              properties:
                org_id: { type: string, format: uuid }
                invitee_email: { type: string, format: email }
      responses:
        '200':
          description: Invite revoked
components:
  securitySchemes:
    BackendApiKey:
      type: http
      scheme: bearer
  parameters:
    OrgId:
      name: orgId
      in: path
      required: true
      schema: { type: string, format: uuid }
  schemas:
    Org:
      type: object
      properties:
        org_id: { type: string, format: uuid }
        name: { type: string }
        url_safe_org_name: { type: string }
        is_saml_configured: { type: boolean }
        is_saml_in_test_mode: { type: boolean }
        max_users: { type: integer }
        metadata:
          type: object
          additionalProperties: true
        domain: { type: string }
        domain_autojoin: { type: boolean }
        domain_restrict: { type: boolean }
        legacy_org_id: { type: string }
        custom_role_mapping_name: { type: string }
        can_setup_saml: { type: boolean }
        created_at: { type: integer }
    OrgPage:
      type: object
      properties:
        orgs:
          type: array
          items: { $ref: '#/components/schemas/Org' }
        total_orgs: { type: integer }
        current_page: { type: integer }
        page_size: { type: integer }
        has_more_results: { type: boolean }
    UserPage:
      type: object
      properties:
        users:
          type: array
          items:
            type: object
            additionalProperties: true
        total_users: { type: integer }
        current_page: { type: integer }
        page_size: { type: integer }
        has_more_results: { type: boolean }
    CreateOrgRequest:
      type: object
      required: [name]
      properties:
        name: { type: string }
        domain: { type: string }
        enable_auto_joining_by_domain: { type: boolean }
        members_must_have_matching_domain: { type: boolean }
        max_users: { type: integer }
        custom_role_mapping_name: { type: string }
        legacy_org_id: { type: string }
    UpdateOrgRequest:
      type: object
      properties:
        name: { type: string }
        can_setup_saml: { type: boolean }
        max_users: { type: integer }
        metadata:
          type: object
          additionalProperties: true
        domain: { type: string }
        require_2fa_by: { type: integer }
        extra_domains:
          type: array
          items: { type: string }
        custom_role_mapping_name: { type: string }
    RoleMapping:
      type: object
      properties:
        custom_role_mapping_name: { type: string }
        num_orgs_subscribed: { type: integer }
        roles:
          type: array
          items:
            type: object
            properties:
              name: { type: string }
              description: { type: string }
              is_internal: { type: boolean }
              is_visible_to_end_user: { type: boolean }
              permissions:
                type: array
                items: { type: string }
    PendingInvite:
      type: object
      properties:
        invitee_email: { type: string, format: email }
        org_id: { type: string, format: uuid }
        org_name: { type: string }
        role_in_org: { type: string }
        additional_roles_in_org:
          type: array
          items: { type: string }
        created_at: { type: integer }
        expires_at: { type: integer }
        inviter_email: { type: string, format: email }
        inviter_user_id: { type: string, format: uuid }