openapi: 3.1.0
info:
  title: '{{ .ProductName }} Admin Account Organization API'
  description: '{{ .ProductName }} Admin API is used to manage users, roles and teamspaces.


    ## Setup requirements


    Authentication is required to perform some operations. Please refer to the [Authentication](https://developers.certifaction.com/en/references/authentication) section to obtain an API Key or token.

    '
  version: ''
servers:
- url: '{{ .APIServerURL }}'
security:
- api_key: []
tags:
- name: Organization
  description: Manage your organization, users, and roles.
paths:
  /organization:
    get:
      tags:
      - Organization
      summary: Get your organization
      operationId: getOrganization
      responses:
        '200':
          description: Organization details fetched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/organization'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/internal_server_error'
  /organization/{id}/user:
    post:
      tags:
      - Organization
      summary: Invite user
      description: A user could be invited multiple times, assuming he didn't accept the invite yet. An email is sent out for each invitation
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the organization to which you want to invite the user
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/organization_user_invite'
      responses:
        '200':
          description: Invited
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internal_server_error'
    delete:
      tags:
      - Organization
      summary: Remove a user from an organization
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the organization
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              anyOf:
              - properties:
                  user_uid:
                    type: string
                    description: The UID of the user to remove
                required:
                - user_uid
              - properties:
                  invite_email:
                    description: The email of the invited user to remove
                    type: string
                required:
                - invite_email
      responses:
        '200':
          description: User removed successfully
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internal_server_error'
  /organization/{organization_id}/role:
    post:
      tags:
      - Organization
      summary: Change the role of a user
      description: Change a user's role in an organization, using either user UID or invite email.
      parameters:
      - name: organization_id
        in: path
        required: true
        description: The ID of the organization
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/organization_role_assign'
      responses:
        '200':
          description: Role updated successfully
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internal_server_error'
components:
  responses:
    conflict:
      description: Conflict detected in the request. For example, a user might have already been joined an organization.
    bad_request:
      description: The request is not properly formed. For example, the content could not be read.
    internal_server_error:
      description: An error occurred on the server
    not_found:
      description: The requested resource was not found.
    forbidden:
      description: You do not have permission to carry out the operation. For example you might not have the required role.
    unauthorized:
      description: You are not authorized to carry out the operation. Check that your API key is correct.
  requestBodies:
    organization_role_assign:
      content:
        application/json:
          schema:
            type: object
            properties:
              user_uid:
                type: string
                description: Either user_uid OR invite_email have to be set, depending if the user already joined or not
              invite_email:
                type: string
              role_id:
                type: string
    organization_user_invite:
      content:
        application/json:
          schema:
            type: object
            properties:
              email:
                type: string
              role_id:
                type: string
              send_email:
                type: boolean
                description: Whether to send an email invitation. Default is true if not specified.
  schemas:
    organization:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          minLength: 2
          maxLength: 80
        name_verified:
          type: boolean
        email:
          type: string
          format: email
          nullable: true
        organization_users:
          type: array
          items:
            $ref: '#/components/schemas/organization_user'
        quota:
          type: integer
          nullable: true
        legacy_credits:
          type: boolean
        roles:
          type: array
          items:
            $ref: '#/components/schemas/organization_role'
    organization_user:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/user'
        role:
          type: string
          deprecated: true
        status:
          type: string
        invite_email:
          type: string
          format: email
          nullable: true
        organization:
          type: boolean
        is_admin:
          type: boolean
        roles:
          type: array
          items:
            $ref: '#/components/schemas/organization_role'
        teamspaces:
          type: array
          items:
            $ref: '#/components/schemas/team_space_description'
          nullable: true
    user:
      type: object
      properties:
        id:
          type: integer
        uid:
          type: string
        email:
          type: string
        name:
          type: string
        permissions:
          type: array
          items:
            type: string
        quota:
          type: integer
        subscription_type:
          type: string
        theme:
          type: object
          properties:
            name:
              type: string
          required:
          - name
        name_verified:
          type: boolean
    team_space_description:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    organization_role:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        default:
          type: boolean
        admin:
          type: boolean
  securitySchemes:
    api_key:
      name: Authorization
      in: header
      type: apiKey