CloudTruth Invitations API

openapi: 3.2.0
info:
  title: CloudTruth Management Invitations API
  version: v1
  description: CloudTruth centralizes your configuration parameters and secrets making them easier to manage and use as a team.
  contact:
    name: CloudTruth Support
    email: support@cloudtruth.com
tags:
- name: Invitations
paths:
  /api/v1/invitations/:
    get:
      operationId: invitations_list
      parameters:
      - in: query
        name: email
        schema:
          type: string
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: role
        schema:
          type: string
          enum:
          - ADMIN
          - CONTRIB
          - NO_SECRETS
          - OWNER
          - VIEWER
        description: 'The role that the user will have in the organization, should the user accept.


          * `OWNER` - Owner

          * `ADMIN` - Administrator

          * `CONTRIB` - Contributor

          * `VIEWER` - Viewer

          * `NO_SECRETS` - NoSecretsViewer'
      - in: query
        name: state
        schema:
          type: string
          enum:
          - accepted
          - bounced
          - pending
          - sent
        description: 'The current state of the invitation.


          * `pending` - Pending

          * `sent` - Sent

          * `accepted` - Accepted

          * `bounced` - Bounced'
      tags:
      - Invitations
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedInvitationList'
          description: ''
      summary: Invitations list
      x-summary-source: derived
    post:
      operationId: invitations_create
      description: Extend an invitation for someone else to join your organization.
      summary: Create an invitation
      tags:
      - Invitations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvitationCreate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/InvitationCreate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/InvitationCreate'
        required: true
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invitation'
          description: ''
        '403':
          description: Permission denied.  Is the invitation role more permissive than your own?
        '404':
          description: Bad Request.  Is there already an invitation for that email?
  /api/v1/invitations/{id}/:
    get:
      operationId: invitations_retrieve
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
          description: The unique identifier of an invitation.
        required: true
      tags:
      - Invitations
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invitation'
          description: ''
      summary: Invitations retrieve
      x-summary-source: derived
    put:
      operationId: invitations_update
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
          description: The unique identifier of an invitation.
        required: true
      tags:
      - Invitations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Invitation'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Invitation'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Invitation'
        required: true
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invitation'
          description: ''
      summary: Invitations update
      x-summary-source: derived
    patch:
      operationId: invitations_partial_update
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
          description: The unique identifier of an invitation.
        required: true
      tags:
      - Invitations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedInvitation'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedInvitation'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedInvitation'
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invitation'
          description: ''
      summary: Invitations partial update
      x-summary-source: derived
    delete:
      operationId: invitations_destroy
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
          description: The unique identifier of an invitation.
        required: true
      tags:
      - Invitations
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '204':
          description: No response body
      summary: Invitations destroy
      x-summary-source: derived
  /api/v1/invitations/{id}/accept/:
    post:
      operationId: invitations_accept_create
      description: 'Accept an invitation to join an organization.


        The email address used to log in and accept the invitation must match

        the email address specified by the inviting user when creating the invitation.


        On success the client receives the invitation record as it was updated.

        The client should then regenerate the JWT with the organization scope and

        proceed to the default landing page.'
      summary: Accept an invitation
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: The invitation ID.
        required: true
      tags:
      - Invitations
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invitation'
          description: The invitation was accepted.  The client should obtain an organization scope token and proceed to the landing page.
        '403':
          description: Permission denied.  The accepting user's email may not match the invitation?
        '404':
          description: Bad Request.  The invitation does not exist or has already been accepted?
  /api/v1/invitations/{id}/public/:
    get:
      operationId: invitations_public_retrieve
      description: 'Unauthenticated metadata fetch for the invite landing page.


        Returns the org name, inviter name, role, and invitee email so the

        landing UI can render " invited you to join as

        " before the user has authenticated. The invitee already

        knows their own email (the link arrived in their inbox), so

        including it here is not a new disclosure.


        In-flight invitations (PENDING / SENT / BOUNCED) return the full

        landing metadata. BOUNCED means the email send failed but the row

        still exists; if the invitee somehow has the link (forwarded,

        etc.) the landing should still work.


        ACCEPTED returns a minimal `{id, state}` body instead of 404:

        invitees routinely re-click the only link they have (or the SPA

        re-fetches the landing right after accepting), and a 404 reads as

        "your invitation is broken" — which sends them and their admins

        into resend/re-invite loops. Revealing only that this unguessable

        link was used (no org name, inviter, or email) lets the landing

        page say "already accepted — sign in" without disclosing the org

        context we deliberately withhold for terminal invitations.


        Unknown IDs (including revoked invitations, whose rows are

        deleted) return 404.'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
          description: The unique identifier of an invitation.
        required: true
      tags:
      - Invitations
      security:
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationPublic'
          description: ''
      summary: Invitations public retrieve
      x-summary-source: derived
  /api/v1/invitations/{id}/resend/:
    post:
      operationId: invitations_resend_create
      description: Re-send an invitation to the recipient.
      summary: Resend an invitation
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: The invitation ID.
        required: true
      tags:
      - Invitations
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invitation'
          description: The invitation state was reset to `pending`, which causes it to get sent again.  The most recent state is returned.  Clients should check the state.
        '404':
          description: Bad Request.  Was the invitation already accepted?
components:
  schemas:
    PatchedInvitation:
      type: object
      properties:
        url:
          type: string
          format: uri
          readOnly: true
        id:
          type: string
          format: uuid
          readOnly: true
          description: The unique identifier of an invitation.
        email:
          type: string
          format: email
          description: The email address of the user to be invited.
          maxLength: 254
        role:
          allOf:
          - $ref: '#/components/schemas/RoleEnum'
          description: 'The role that the user will have in the organization, should the user accept.


            * `OWNER` - Owner

            * `ADMIN` - Administrator

            * `CONTRIB` - Contributor

            * `VIEWER` - Viewer

            * `NO_SECRETS` - NoSecretsViewer'
        inviter:
          type: string
          format: uri
          readOnly: true
          description: The user that created the invitation.
        inviter_name:
          type: string
          readOnly: true
          description: The name of the user that created the invitation.
        state:
          type: string
          readOnly: true
          description: The current state of the invitation.
        state_detail:
          type: string
          readOnly: true
          description: Additional details about the state of the invitation.
        membership:
          type:
          - string
          - 'null'
          format: uri
          readOnly: true
          description: The resulting membership, should the user accept.
        organization:
          type: string
          format: uri
          readOnly: true
          description: The organization that the user will become a member of, should the user accept.
    Invitation:
      type: object
      properties:
        url:
          type: string
          format: uri
          readOnly: true
        id:
          type: string
          format: uuid
          readOnly: true
          description: The unique identifier of an invitation.
        email:
          type: string
          format: email
          description: The email address of the user to be invited.
          maxLength: 254
        role:
          allOf:
          - $ref: '#/components/schemas/RoleEnum'
          description: 'The role that the user will have in the organization, should the user accept.


            * `OWNER` - Owner

            * `ADMIN` - Administrator

            * `CONTRIB` - Contributor

            * `VIEWER` - Viewer

            * `NO_SECRETS` - NoSecretsViewer'
        inviter:
          type: string
          format: uri
          readOnly: true
          description: The user that created the invitation.
        inviter_name:
          type: string
          readOnly: true
          description: The name of the user that created the invitation.
        state:
          type: string
          readOnly: true
          description: The current state of the invitation.
        state_detail:
          type: string
          readOnly: true
          description: Additional details about the state of the invitation.
        membership:
          type:
          - string
          - 'null'
          format: uri
          readOnly: true
          description: The resulting membership, should the user accept.
        organization:
          type: string
          format: uri
          readOnly: true
          description: The organization that the user will become a member of, should the user accept.
      required:
      - email
      - id
      - inviter
      - inviter_name
      - membership
      - organization
      - role
      - state
      - state_detail
      - url
    InvitationCreate:
      type: object
      properties:
        email:
          type: string
          format: email
          description: The email address of the user to be invited.
          maxLength: 254
        role:
          allOf:
          - $ref: '#/components/schemas/RoleEnum'
          description: 'The role that the user will have in the organization, should the user accept.


            * `OWNER` - Owner

            * `ADMIN` - Administrator

            * `CONTRIB` - Contributor

            * `VIEWER` - Viewer

            * `NO_SECRETS` - NoSecretsViewer'
      required:
      - email
      - role
    RoleEnum:
      enum:
      - OWNER
      - ADMIN
      - CONTRIB
      - VIEWER
      - NO_SECRETS
      type: string
      description: '* `OWNER` - Owner

        * `ADMIN` - Administrator

        * `CONTRIB` - Contributor

        * `VIEWER` - Viewer

        * `NO_SECRETS` - NoSecretsViewer'
    InvitationPublic:
      type: object
      description: 'Serializer for the unauthenticated invite landing page that shows an

        invitee what they''re being invited to before they sign in or create

        an account. Returns only the fields needed to render that page — no

        hyperlinks requiring auth context, no membership references. The

        invitee''s own email is included because they already know it (the

        link came in their inbox) and the landing page renders "invited as

        <email>" to confirm they''re acting on the right invitation.'
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: The unique identifier of an invitation.
        email:
          type: string
          format: email
          description: The email address of the user to be invited.
          maxLength: 254
        role:
          allOf:
          - $ref: '#/components/schemas/RoleEnum'
          description: 'The role that the user will have in the organization, should the user accept.


            * `OWNER` - Owner

            * `ADMIN` - Administrator

            * `CONTRIB` - Contributor

            * `VIEWER` - Viewer

            * `NO_SECRETS` - NoSecretsViewer'
        role_label:
          type: string
          readOnly: true
          description: Human-readable role label (the underlying value is in `role`).
        inviter_name:
          type: string
          readOnly: true
          description: The name of the user that created the invitation.
        organization_id:
          type: string
          readOnly: true
          description: UUID of the organization. Used by the landing page to construct the post-login accept URL.
        organization_name:
          type: string
          readOnly: true
          description: Display name of the organization extending the invitation.
        auth0_organization_id:
          type:
          - string
          - 'null'
          readOnly: true
          description: Auth0 Organization ID to pass as the `organization` parameter when redirecting the invitee to Auth0. Only populated when the organization has SSO enabled — the accept endpoint requires an org-scoped Auth0 login in that case; non-SSO logins must not be org-scoped or Auth0 may reject connections not enabled for the org.
        state:
          type: string
          readOnly: true
          description: The current state of the invitation.
      required:
      - auth0_organization_id
      - email
      - id
      - inviter_name
      - organization_id
      - organization_name
      - role
      - role_label
      - state
    PaginatedInvitationList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Invitation'
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: Authorization
      type: apiKey
      description: "\nUse your CloudTruth API Key to authenticate to the API.  You can get\nan API Key by creating a Service Account.  During setup of the Service\nAccount you will generate a long-lived API key intended for use by automation\nand API clients.  Access through the service account will be audited separately\nfrom any other user.\n\nIf you are just trying to use the API in a normal workflow, this is likely the\nauthentication mechanism you want to use.\n\nTo use the API Key, place your API Key in the Authorization header as 'Api-Key APIKEY', where\nAPIKEY is your CloudTruth API Key.  For example:\n\n    Authorization: Api-Key fskur.ghlsiudhrg84so938r5u\n        "
    JWTAuth:
      in: header
      name: Authorization
      type: apiKey
      description: "\nUse your JWT to authenticate to the API.  This is how the CloudTruth\nWeb UI authenticates to the backend.  It requires a user to have already logged in\nand gotten a JWT from the login process.  This is usually done by an Auth0 authentication\nflow from one of the Auth0 javascript libraries.  Alternatively, you can pull the\nJWT from your browser if you have a logged in session with the CloudTruth UI.\n\nThis authentication mechanism is intended for deeper integrations into the CloudTruth\nsystem, where you want to handle the user logins directly in your application.  For\nnormal API use, you likely want the Api-Key authentication header and not this one.\n\nTo use the JWT, place your JWT in the Authorization header as 'Bearer JWT', where\nJWT is your JWT.  For example:\n\n    Authorization: Bearer eyJhbGciOiJIkuydfy.eyJzdWIiOiIxMjM....\n        "
    tokenAuth:
      type: http
      scheme: bearer
externalDocs:
  url: https://docs.cloudtruth.com/