openapi: 3.2.0
info:
  title: Nordstellar Partners API
  description: The NordStellar Partners API provides a suite of tools for partners to manage their accounts and customer relationships. It enables partners to create and manage partner entities, onboard administrators, and access detailed usage reports for billing and monitoring purposes.
  contact:
    name: Vakaris Noreika
    email: vakaris.noreika@nordsec.com
  version: '1'
servers:
- url: https://platform-partners-api.nordstellar.com
security:
- ApiKey: []
tags:
- name: Partners
paths:
  /v1/partners/{partner-id}/administrator-invitations:
    post:
      tags:
      - Partners
      summary: Invite multiple administrators to a partner.
      description: 'Invite multiple administrators to a partner account in a single request. Sends emails with registration instructions.

        Response lists successful and failed invitations.'
      parameters:
      - name: partner-id
        in: path
        description: Unique identifier of the partner
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/InviteAdmin.Contract.PartnerAdmin'
        required: true
      responses:
        '200':
          description: The request has succeeded
          content:
            application/json: {}
        '207':
          description: The request has succeeded, but the response contains multiple status codes for different parts of the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteAdmin.Contract.Response'
              example:
                successful:
                - id: 4b92e32d-0068-460f-85d2-644dc80f4586
                  email: example@example.com
                failed:
                - request:
                    email: example2@example.com
                    user_name: null
                  details: Failed to invite partner admin due to some reason.
        '400':
          description: The server cannot or will not process the request due to an error made by the client.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-400-bad-request
                title: Bad Request
                status: 400
                instance: /v1/resource/123
                errors:
                  FIELD A:
                  - ERROR 1
                  - ERROR 2
                  FIELD B:
                  - ERROR 3
        '401':
          description: The server has received and understood the request but is unable to authenticate it.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-401-unauthorized
                title: Unauthorized
                status: 401
                detail: User unauthorized.
                instance: /v1/resource/123
        '403':
          description: The server has received and understood the request but is unable to authorize it.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-403-forbidden
                title: Forbidden
                status: 403
                detail: The user is not allowed to do an action for the specified resource.
                instance: /v1/resource/123
        '500':
          description: The server has encountered a situation it does not know how to handle.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-500-internal-server-error
                title: Internal Server Error
                status: 500
                detail: Something went wrong
                instance: /v1/resource/123
  /v1/partners/{partner-id}/usage-reports:
    get:
      tags:
      - Partners
      summary: Retrieves historical usage data for a specific partner.
      description: 'Retrieves historical usage data for a specific partner organization.

        Data includes daily snapshots of billable/non-billable asset counts, plan group, and project breakdowns. Supports date filtering.'
      parameters:
      - name: date_from
        in: query
        description: Start full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21
        schema:
          type: string
          format: date
      - name: date_to
        in: query
        description: End full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21
        schema:
          type: string
          format: date
      - name: partner-id
        in: path
        description: Unique identifier of the partner
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The request has succeeded
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Partners.GetUsageReports.PartnerUsageReportModel'
              example:
              - date: '2024-05-15'
                billable_assets_count: 1123
                non_billable_assets_count: 113
                billable_domains_count: 345
                non_billable_domains_count: 12
                plan_group: NSMSP5
                projects:
                - project_id: 1e4d2e74-1c31-4116-a33d-8806e1b3ef29
                  is_billable: false
                  assets_count: 1236
                  domains_count: 357
              - date: '2024-05-16'
                billable_assets_count: 1200
                non_billable_assets_count: 100
                billable_domains_count: 400
                non_billable_domains_count: 15
                plan_group: NSMSP5
                projects:
                - project_id: 1e4d2e74-1c31-4116-a33d-8806e1b3ef29
                  is_billable: true
                  assets_count: 1236
                  domains_count: 357
                - project_id: 2f5d3e85-2b42-4c1a-bb6f-9a7e8c4d5f6a
                  is_billable: true
                  assets_count: 64
                  domains_count: 58
        '400':
          description: The server cannot or will not process the request due to an error made by the client.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-400-bad-request
                title: Bad Request
                status: 400
                instance: /v1/resource/123
                errors:
                  FIELD A:
                  - ERROR 1
                  - ERROR 2
                  FIELD B:
                  - ERROR 3
        '401':
          description: The server has received and understood the request but is unable to authenticate it.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-401-unauthorized
                title: Unauthorized
                status: 401
                detail: User unauthorized.
                instance: /v1/resource/123
        '403':
          description: The server has received and understood the request but is unable to authorize it.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-403-forbidden
                title: Forbidden
                status: 403
                detail: The user is not allowed to do an action for the specified resource.
                instance: /v1/resource/123
        '500':
          description: The server has encountered a situation it does not know how to handle.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-500-internal-server-error
                title: Internal Server Error
                status: 500
                detail: Something went wrong
                instance: /v1/resource/123
  /v1/partners/{partner-id}:
    get:
      tags:
      - Partners
      summary: Retrieves detailed information about a specific partner.
      description: 'Provides comprehensive information about a specific partner.

        Includes basic profile information and usage statistics, including billable and non-billable asset counts.

        Also returns a breakdown of projects associated with the partner.'
      parameters:
      - name: partner-id
        in: path
        description: Unique identifier of the partner
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The request has succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Partners.GetPartner.Response'
              example:
                id: 1e4d2e74-1c31-4116-a33d-8806e1b3ef29
                title: Security
                billable_assets_count: 0
                non_billable_assets_count: 0
                billable_domains_count: 0
                non_billable_domains_count: 0
                plan_group: NSMSP0
                projects:
                - project_id: 1e4d2e74-1c31-4116-a33d-8806e1b3ef29
                  project_name: Security Project
                  is_billable: false
                  assets_count: 234
                  domains_count: 23
                - project_id: 2f5d3e85-2b42-4c1a-bb6f-9a7e8c4d5f6a
                  project_name: Infrastructure Monitoring
                  is_billable: true
                  assets_count: 123
                  domains_count: 18
        '400':
          description: The server cannot or will not process the request due to an error made by the client.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-400-bad-request
                title: Bad Request
                status: 400
                instance: /v1/resource/123
                errors:
                  FIELD A:
                  - ERROR 1
                  - ERROR 2
                  FIELD B:
                  - ERROR 3
        '401':
          description: The server has received and understood the request but is unable to authenticate it.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-401-unauthorized
                title: Unauthorized
                status: 401
                detail: User unauthorized.
                instance: /v1/resource/123
        '403':
          description: The server has received and understood the request but is unable to authorize it.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-403-forbidden
                title: Forbidden
                status: 403
                detail: The user is not allowed to do an action for the specified resource.
                instance: /v1/resource/123
        '500':
          description: The server has encountered a situation it does not know how to handle.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-500-internal-server-error
                title: Internal Server Error
                status: 500
                detail: Something went wrong
                instance: /v1/resource/123
  /v1/partners:
    get:
      tags:
      - Partners
      summary: Retrieves list of partners for a specific organization.
      description: 'Retrieves a paginated list of all partner organizations. Each partner entry includes basic identifying information.

        Supports `limit` and `offset` query params for pagination. Partners are listed by creation date, most recent first.'
      parameters:
      - name: offset
        in: query
        description: Numeric offset of the first element provided on a page representing a collection request
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: Limit to restrict the number of entries on a page
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: The request has succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPartners.Contracts.Response'
              example:
                items:
                - id: 1e4d2e74-1c31-4116-a33d-8806e1b3ef29
                  title: Security
                - id: 2f5d3e85-2b42-4c1a-bb6f-9a7e8c4d5f6a
                  title: SecureFolio
                - id: 3a6b4f96-3c53-5d2b-cd7f-a8b9e5d6f7b8
                  title: Inspection
                - id: 4c7d5e87-4e64-6f3c-de8f-b9a0e6d7f8a9
                  title: InvestSecure+
                - id: 5e8f6a98-5f75-7d4e-ea9f-c0b1f8d9e0a1
                  title: TechSentinel
                self: https://example.com/v1/partners?limit=5
                next: https://example.com/v1/partners?offset=5&limit=5
        '400':
          description: The server cannot or will not process the request due to an error made by the client.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-400-bad-request
                title: Bad Request
                status: 400
                instance: /v1/resource/123
                errors:
                  FIELD A:
                  - ERROR 1
                  - ERROR 2
                  FIELD B:
                  - ERROR 3
        '401':
          description: The server has received and understood the request but is unable to authenticate it.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-401-unauthorized
                title: Unauthorized
                status: 401
                detail: User unauthorized.
                instance: /v1/resource/123
        '500':
          description: The server has encountered a situation it does not know how to handle.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-500-internal-server-error
                title: Internal Server Error
                status: 500
                detail: Something went wrong
                instance: /v1/resource/123
    post:
      tags:
      - Partners
      summary: Creates a new partner.
      description: Creates a new partner. Requires partner email domain, title, optional billing and package selection.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePartner.Contract.Request'
        required: true
      responses:
        '200':
          description: The request has succeeded
          content:
            application/json: {}
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePartner.Contract.Response'
              example:
                id: 1e4d2e74-1c31-4116-a33d-8806e1b3ef29
                email_domain: example.com
                title: Example Partner
                package_id: 2
                billing_information:
                  country: US
                  city: New York
                  address_line1: 123 Example St
                  address_line2: Suite 456
                  postal_code: '10001'
                  state: NY
        '400':
          description: The server cannot or will not process the request due to an error made by the client.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-400-bad-request
                title: Bad Request
                status: 400
                instance: /v1/resource/123
                errors:
                  FIELD A:
                  - ERROR 1
                  - ERROR 2
                  FIELD B:
                  - ERROR 3
        '401':
          description: The server has received and understood the request but is unable to authenticate it.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-401-unauthorized
                title: Unauthorized
                status: 401
                detail: User unauthorized.
                instance: /v1/resource/123
        '403':
          description: The server has received and understood the request but is unable to authorize it.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-403-forbidden
                title: Forbidden
                status: 403
                detail: The user is not allowed to do an action for the specified resource.
                instance: /v1/resource/123
        '500':
          description: The server has encountered a situation it does not know how to handle.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://datatracker.ietf.org/doc/html/rfc9110#name-500-internal-server-error
                title: Internal Server Error
                status: 500
                detail: Something went wrong
                instance: /v1/resource/123
components:
  schemas:
    InviteAdmin.Contract.FailedPartnerAdmin:
      required:
      - details
      - request
      type: object
      properties:
        request:
          $ref: '#/components/schemas/InviteAdmin.Contract.PartnerAdmin'
        details:
          type: string
          description: The reason why the invitation failed.
      additionalProperties: false
    CreatePartner.Contract.BillingInformationResponse:
      required:
      - address_line1
      - address_line2
      - city
      - country
      - postal_code
      - state
      type: object
      properties:
        country:
          type: string
          description: Country code in ISO 3166-1 alpha-2 format.
        city:
          type: string
          description: City name.
        address_line1:
          type: string
          description: Address line 1, typically the street address.
        address_line2:
          type:
          - string
          - 'null'
          description: Address line 2, typically used for additional address information (e.g., apartment number).
        postal_code:
          type: string
          description: Postal code or ZIP code for the address.
        state:
          type:
          - string
          - 'null'
          description: State or province name, if applicable.
      additionalProperties: false
    Partners.GetPartner.Project:
      required:
      - assets_count
      - domains_count
      - is_billable
      - project_id
      - project_name
      type: object
      properties:
        project_id:
          type: string
          description: Unique identifier of the project.
          format: uuid
        project_name:
          type: string
          description: Name of the project.
        is_billable:
          type: boolean
          description: Is the project billable.
        assets_count:
          type: integer
          description: Count of assets in the project.
          format: int32
        domains_count:
          type: integer
          description: Count of domains in the project.
          format: int32
      additionalProperties: false
    CreatePartner.Contract.BillingInformationRequest:
      type: object
      properties:
        country:
          type: string
          description: Country code in ISO 3166-1 alpha-2 format.
        city:
          type: string
          description: City name.
        address_line1:
          type: string
          description: Address line 1, typically the street address.
        address_line2:
          type:
          - string
          - 'null'
          description: Address line 2, typically used for additional address information (e.g., apartment number).
        postal_code:
          type: string
          description: Postal code or ZIP code for the address.
        state:
          type:
          - string
          - 'null'
          description: State or province name, if applicable.
      additionalProperties: false
    Partners.GetPartner.Response:
      required:
      - billable_assets_count
      - billable_domains_count
      - id
      - non_billable_assets_count
      - non_billable_domains_count
      - projects
      - title
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the partner.
          format: uuid
        title:
          type: string
          description: Title of the partner.
        billable_assets_count:
          type: integer
          description: Number of assets that are billable.
          format: int32
        non_billable_assets_count:
          type: integer
          description: Number of assets that are not billable.
          format: int32
        billable_domains_count:
          type: integer
          description: Number of domains that are billable.
          format: int32
        non_billable_domains_count:
          type: integer
          description: Number of domains that are not billable.
          format: int32
        plan_group:
          type: string
          description: Pricing group of the partner.
          readOnly: true
        projects:
          type: array
          items:
            $ref: '#/components/schemas/Partners.GetPartner.Project'
          description: Collection of projects associated with the partner.
      additionalProperties: false
    InviteAdmin.Contract.PartnerAdmin:
      required:
      - email
      type: object
      properties:
        email:
          type: string
          description: Email address of the partner admin that was invited.
        user_name:
          type:
          - string
          - 'null'
          description: Optional name for the partner admin. If not provided, it is derived from the email address.
      additionalProperties: false
    CreatePartner.Contract.Response:
      required:
      - billing_information
      - email_domain
      - id
      - package_id
      - title
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the partner.
          format: uuid
        email_domain:
          type: string
          description: Email domain associated with the partner.
        title:
          type: string
          description: Title of the partner.
        package_id:
          type: integer
          description: Unique identified of the package.
          format: int32
        billing_information:
          $ref: '#/components/schemas/CreatePartner.Contract.BillingInformationResponse'
      additionalProperties: false
    InviteAdmin.Contract.SucceededPartnerAdmin:
      required:
      - email
      - id
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the partner admin that was successfully invited.
          format: uuid
        email:
          type: string
          description: Email address of the partner admin that was successfully invited.
      additionalProperties: false
    ListPartners.Contracts.Partner:
      required:
      - id
      - title
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the partner
          format: uuid
        title:
          type: string
          description: Title of the partner
      additionalProperties: false
    Partners.GetUsageReports.ProjectUsageReport:
      required:
      - assets_count
      - domains_count
      - is_billable
      - project_id
      type: object
      properties:
        project_id:
          type: string
          description: Unique identifier of the project.
          format: uuid
        is_billable:
          type: boolean
          description: Is the project billable.
        assets_count:
          type: integer
          description: Count of assets in the project.
          format: int32
        domains_count:
          type: integer
          description: Count of domains in the project.
          format: int32
      additionalProperties: false
    CreatePartner.Contract.Request:
      type: object
      properties:
        email_domain:
          type: string
          description: Email domain associated with the partner.
        title:
          type: string
          description: Title of the partner.
        package_id:
          type: integer
          description: Unique identifier of the package.
          format: int32
        billing_information:
          $ref: '#/components/schemas/CreatePartner.Contract.BillingInformationRequest'
      additionalProperties: false
    ListPartners.Contracts.Response:
      required:
      - items
      type: object
      properties:
        self:
          type: string
          description: Url link pointing to the same page
        next:
          type:
          - string
          - 'null'
          description: Url link pointing to the next page
        items:
          type: array
          items:
            $ref: '#/components/schemas/ListPartners.Contracts.Partner'
          description: Collection of partners
      additionalProperties: false
    ValidationProblemDetails:
      required:
      - detail
      - instance
      - status
      - title
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the type of the problem.
        title:
          type: string
          description: A short summary of the type of the problem.
        status:
          maximum: 599
          minimum: 400
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type: string
          description: An explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A unique identifier of this occurrence of the problem. Include it in your support request.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: A map of problems with the request that need to be solved by the requester, wherein the key is the source of the problem, and the value is its details.
      additionalProperties: {}
      description: Error information that describes why the request has failed. Format conforms to IETF's RFC 9457.
      externalDocs:
        description: RFC 9457 "Problem Details for HTTP APIs" by Internet Engineering Task Force
        url: https://datatracker.ietf.org/doc/html/rfc9457
    ProblemDetails:
      required:
      - detail
      - instance
      - status
      - title
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the type of the problem.
        title:
          type: string
          description: A short summary of the type of the problem.
        status:
          maximum: 599
          minimum: 400
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type: string
          description: An explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A unique identifier of this occurrence of the problem. Include it in your support request.
      additionalProperties: {}
      description: Error information that describes why the request has failed. Format conforms to IETF's RFC 9457.
      externalDocs:
        description: RFC 9457 "Problem Details for HTTP APIs" by Internet Engineering Task Force
        url: https://datatracker.ietf.org/doc/html/rfc9457
    Partners.GetUsageReports.PartnerUsageReportModel:
      required:
      - billable_assets_count
      - billable_domains_count
      - date
      - non_billable_assets_count
      - non_billable_domains_count
      - plan_group
      - projects
      type: object
      properties:
        date:
          type: string
          description: Date of the report in ISO 8601 format (YYYY-MM-DD).
        billable_assets_count:
          type: integer
          description: Number of assets that are billable.
          format: int32
        non_billable_assets_count:
          type: integer
          description: Number of assets that are not billable.
          format: int32
        billable_domains_count:
          type: integer
          description: Number of domains that are billable.
          format: int32
        non_billable_domains_count:
          type: integer
          description: Number of domains that are not billable.
          format: int32
        plan_group:
          type: string
          description: Pricing group of the partner.
        projects:
          type: array
          items:
            $ref: '#/components/schemas/Partners.GetUsageReports.ProjectUsageReport'
          description: Collection of projects associated with the partner.
      additionalProperties: false
    InviteAdmin.Contract.Response:
      required:
      - failed
      - successful
      type: object
      properties:
        successful:
          type: array
          items:
            $ref: '#/components/schemas/InviteAdmin.Contract.SucceededPartnerAdmin'
          description: Collection of successfully invited partner admins.
        failed:
          type: array
          items:
            $ref: '#/components/schemas/InviteAdmin.Contract.FailedPartnerAdmin'
          description: Collection of partner admins that failed to be invited.
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: apiKey
      description: API key to access the API
      name: Api-Key
      in: header