openapi: 3.0.1
info:
  title: Invite User Service
  description: The invite user Service provides APIs for inviting a user to your tenant.
  version: '2.0'
tags:
  - name: InviteUserService
security:
  - Authorization: []
paths:
  /users/invitations:
    post:
      summary: |-
        *
        Invites a list of users to the Phoenix platform.
        Each invited email represents a new user in the platform. The invited user will
        receive an email with a link to accept the invitation. To be clear: an invitation is *not* to create an account, but
        to join a tenant. Registering for an account is done separately through an IdP (such as Ping). Inviting without
        registering will render a "self" tenant.
      description: 'Permission level: Read-Write'
      operationId: InviteUserService_InviteUsers
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2InviteUsersResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v2InviteUsersRequest'
        required: true
      tags:
        - InviteUserService
  /users/invitations/groups:
    get:
      summary: |-
        *
        Lists all generic invites in a tenant. Paginated and with Filter.
      description: 'Permission level: Read'
      operationId: InviteUserService_ListGenericInvitations
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2ListGenericInvitationsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      parameters:
        - name: tenantId
          description: 'The tenant of the invitations, Default: tenant from the authorization token'
          in: query
          required: false
          schema:
            type: string
        - name: isInactive
          description: |-
            Filter only inactive invitations. An invitation is considered inactive when it's expired or has no remaining seats available. Default: false.
            By default this field is false, listing only active invitations.
          in: query
          required: false
          schema:
            type: boolean
        - name: specificFilter.displayName
          in: query
          required: false
          schema:
            type: string
        - name: searchMatchType
          description: ENUM to switch between the type of string matching you want on a query. Default = REGEX, Required = false.
          in: query
          required: false
          schema:
            type: string
            enum:
              - REGEX
              - EXACT
            default: REGEX
        - name: sortField
          description: 'Sort field, valid values: displayName Default: displayName, Required: false'
          in: query
          required: false
          schema:
            type: string
        - name: sortType
          description: 'Sort Type for the results, Default: ASC, Required: false'
          in: query
          required: false
          schema:
            type: string
            enum:
              - NONE
              - ASC
              - DESC
            default: NONE
        - name: pageSize
          description: |-
            Requested size of the next page of data.
            If not set, the default page size is 10, Required: false.
          in: query
          required: false
          schema:
            type: integer
            format: int32
        - name: pageToken
          description: 'MongoDB Field, describes the encoded page token for page traversal, Required: false'
          in: query
          required: false
          schema:
            type: string
      tags:
        - InviteUserService
    post:
      summary: |-
        *
        Creates a generic invitation that a user can utilize to join the Platform.
        An invitation is *not* to create an account, but to join a tenant. Registering for an account is done separately through an IdP (such as Ping).
      description: 'Permission level: Read-Write'
      operationId: InviteUserService_CreateGenericInvitation
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2CreateGenericInvitationResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v2CreateGenericInvitationRequest'
        required: true
      tags:
        - InviteUserService
  /users/invitations/{inviteToken}:
    get:
      summary: |-
        *
        Retrieve an Invitation. Can be a Generic or User invitation.
      description: 'Permission level: Read'
      operationId: InviteUserService_GetInvitation
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2GetInvitationResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      parameters:
        - name: inviteToken
          description: 'the invite token to be retrieved. Required: true'
          in: path
          required: true
          schema:
            type: string
      tags:
        - InviteUserService
    delete:
      summary: |-
        *
        Deletes an invite token for the Phoenix platform.
      description: 'Permission level: Read-Write'
      operationId: InviteUserService_DeleteInviteToken
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      parameters:
        - name: inviteToken
          description: the token to be deleted
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          description: 'the Tenant that the users will be invited to, Default : tenant from the authorization token'
          in: query
          required: false
          schema:
            type: string
      tags:
        - InviteUserService
servers:
  - url: https://prod-ui-zwseuprod01p.pp.zebra.com/api
    description: EU Server
  - url: https://prod-ui-zwsusprod01p.pp.zebra.com/api
    description: NA Server
components:
  schemas:
    commonsSearchMatchType:
      type: string
      enum:
        - REGEX
        - EXACT
      default: REGEX
    commonsSortType:
      type: string
      enum:
        - NONE
        - ASC
        - DESC
      default: NONE
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties: {}
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    v2CreateGenericInvitationRequest:
      type: object
      properties:
        tenantId:
          type: string
          title: 'the Tenant that the users will be invited to. Default: tenant from the authorization token. Required: false'
        expiresAt:
          type: string
          format: date-time
          title: 'The expiration date of the invite. Required: true'
        numberOfSeats:
          type: integer
          format: int32
          description: 'The maximum number of users that can join the platform using this invite. Required: true. Must be greater than zero.'
        displayName:
          type: string
          description: 'The display name of the invite. Required: false.'
        site:
          type: string
          description: 'The site of the invite. Required: false.'
        owner:
          $ref: '#/components/schemas/v2UniqueUserProto'
    v2CreateGenericInvitationResponse:
      type: object
      properties:
        invite:
          $ref: '#/components/schemas/v2GenericInvite'
    v2GenericInvite:
      type: object
      properties:
        tenantId:
          type: string
          title: the tenant that the users will be invited to
        inviteToken:
          type: string
          title: the unique identifier for an invitation
        inviteUrl:
          type: string
          title: the URL that should be used to join the platform
        numberOfSeats:
          type: integer
          format: int32
          title: The maximum number of users that can join the platform using this invite
        remainingSeats:
          type: integer
          format: int32
          title: The remaining number of users that can join the platform using this invite
        displayName:
          type: string
          title: The display name of the invite
        site:
          $ref: '#/components/schemas/v2SiteInviteProto'
        owner:
          $ref: '#/components/schemas/v2UniqueUserProto'
        expiresAt:
          type: string
          format: date-time
          title: The expiration date of the invite
        createdAt:
          type: string
          format: date-time
          title: the time of creation of this entity
    v2GenericInviteSpecificFilter:
      type: object
      properties:
        displayName:
          type: string
    v2GetInvitationResponse:
      type: object
      properties:
        invitation:
          $ref: '#/components/schemas/v2Invitation'
    v2Invitation:
      type: object
      properties:
        tenantId:
          type: string
          title: the tenant that the users will be invited to
        email:
          type: string
          description: the email of the user. Only present if is_generic is false.
        inviteToken:
          type: string
          title: the unique identifier for an invitation
        inviteUrl:
          type: string
          title: the URL that should be used to join the platform
        isGeneric:
          type: boolean
          title: boolean to identify if it's a generic invitation
        numberOfSeats:
          type: integer
          format: int32
          title: The maximum number of users that can join the platform using this invite
        remainingSeats:
          type: integer
          format: int32
          title: The remaining number of users that can join the platform using this invite
        displayName:
          type: string
          title: The display name of the invite
        site:
          $ref: '#/components/schemas/v2SiteInviteProto'
        owner:
          $ref: '#/components/schemas/v2UniqueUserProto'
        expiresAt:
          type: string
          format: date-time
          title: The expiration date of the invite
        createdAt:
          type: string
          format: date-time
          title: the time of creation of this entity
    v2InviteUsersRequest:
      type: object
      properties:
        tenantId:
          type: string
          title: 'the Tenant that the users will be invited to. Default: tenant from the authorization token. Required: false'
        expiresAt:
          type: string
          format: date-time
          title: 'The expiration date of the invite. Required: true'
        emails:
          type: array
          items:
            type: string
          description: the list of emails which will receive the invite link.
        templateId:
          type: string
          title: |-
            Reference to a `template` which is a template that defines the structure of a message; See the Email Sms Template for more details
            Default: base_template of the tenant. Required: false
        content:
          type: string
          title: 'content of the template. Required: false'
    v2InviteUsersResponse:
      type: object
      properties:
        invitationTokens:
          type: object
          additionalProperties:
            type: string
          title: |-
            A map containing emails and invitation tokens.
            key: the invited email (empty if it's a generic invitation)
            value: the invitation token
    v2ListGenericInvitationsResponse:
      type: object
      properties:
        invites:
          type: array
          items:
            $ref: '#/components/schemas/v2GenericInvite'
          title: list of generic invites for the given tenant
        nextPageToken:
          type: string
          title: next page token
    v2SiteInviteProto:
      type: object
      properties:
        tenantId:
          type: string
        name:
          type: string
      description: |-
        Type definition that includes the site of the invite. This is necessary so we can extend
        this type with the site details in the GraphQL Mesh.
    v2UniqueUserProto:
      type: object
      properties:
        tenantId:
          type: string
          description: 'The ID of the tenant. Required: false. Defaults to the tenant of the user making the call.'
        userId:
          type: string
          description: 'The user ID. Required: true.'
        firstName:
          type: string
          description: 'The first name. Required: false.'
        lastName:
          type: string
          description: 'The last name. Required: false.'
    googleRpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
  securitySchemes:
    Authorization:
      type: apiKey
      description: Bearer token
      name: Authorization
      in: header