NetBird IDP SCIM Integrations API

openapi: 3.1.0
info:
  title: NetBird REST Accounts IDP SCIM Integrations API
  description: API to manipulate groups, rules, policies and retrieve information about peers and users
  version: 0.0.1
servers:
- url: https://api.netbird.io
  description: Default server
security:
- BearerAuth: []
- TokenAuth: []
tags:
- name: IDP SCIM Integrations
  description: Manage generic SCIM identity provider integrations for user and group sync.
  x-cloud-only: true
paths:
  /api/integrations/scim-idp:
    post:
      tags:
      - IDP SCIM Integrations
      summary: Create SCIM IDP Integration
      description: Creates a new SCIM integration
      operationId: createSCIMIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScimIntegrationRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimIntegration'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - IDP SCIM Integrations
      summary: Get All SCIM IDP Integrations
      description: Retrieves all SCIM IDP integrations for the authenticated account
      operationId: getAllSCIMIntegrations
      responses:
        '200':
          description: A list of SCIM IDP integrations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScimIntegration'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/scim-idp/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: The unique identifier of the SCIM IDP integration.
      schema:
        type: integer
        format: int64
        example: 1
    get:
      tags:
      - IDP SCIM Integrations
      summary: Get SCIM IDP Integration
      description: Retrieves an SCIM IDP integration by ID.
      operationId: getSCIMIntegration
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimIntegration'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - IDP SCIM Integrations
      summary: Update SCIM IDP Integration
      description: Updates an existing SCIM IDP Integration.
      operationId: updateSCIMIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScimIntegrationRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimIntegration'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - IDP SCIM Integrations
      summary: Delete SCIM IDP Integration
      description: Deletes an SCIM IDP integration by ID.
      operationId: deleteSCIMIntegration
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: {}
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/scim-idp/{id}/token:
    parameters:
    - name: id
      in: path
      required: true
      description: The unique identifier of the SCIM IDP integration.
      schema:
        type: integer
        format: int64
        example: 1
    post:
      tags:
      - IDP SCIM Integrations
      summary: Regenerate SCIM Token
      description: Regenerates the SCIM API token for an SCIM IDP integration.
      operationId: regenerateSCIMToken
      responses:
        '200':
          description: Token regenerated successfully. Returns the new token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimTokenResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/scim-idp/{id}/logs:
    parameters:
    - name: id
      in: path
      required: true
      description: The unique identifier of the SCIM IDP integration.
      schema:
        type: integer
        format: int64
        example: 1
    get:
      tags:
      - IDP SCIM Integrations
      summary: Get SCIM Integration Sync Logs
      description: Retrieves synchronization logs for a SCIM IDP integration.
      operationId: getSCIMIntegrationLogs
      responses:
        '200':
          description: Successfully retrieved the integration sync logs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdpIntegrationSyncLog'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    UpdateScimIntegrationRequest:
      allOf:
      - $ref: '#/components/schemas/IntegrationEnabled'
      - $ref: '#/components/schemas/IntegrationSyncFilters'
      - type: object
        description: Request payload for updating an SCIM IDP integration
        properties:
          prefix:
            type: string
            description: The connection prefix used for the SCIM provider
    IntegrationEnabled:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether the integration is enabled
          example: true
    ScimTokenResponse:
      type: object
      description: Response containing the regenerated SCIM token
      required:
      - auth_token
      properties:
        auth_token:
          type: string
          description: The newly generated SCIM API token
          example: nbs_F3f0d...
    ScimIntegration:
      allOf:
      - $ref: '#/components/schemas/IntegrationEnabled'
      - $ref: '#/components/schemas/IntegrationSyncFilters'
      - type: object
        description: Represents a SCIM IDP integration
        required:
        - id
        - enabled
        - prefix
        - provider
        - group_prefixes
        - user_group_prefixes
        - auth_token
        - last_synced_at
        properties:
          id:
            type: integer
            format: int64
            description: The unique identifier for the integration
            example: 123
          prefix:
            type: string
            description: The connection prefix used for the SCIM provider
          provider:
            type: string
            description: Name of the SCIM identity provider
          auth_token:
            type: string
            description: SCIM API token (full on creation, masked otherwise)
            example: nbs_abc***********************************
          last_synced_at:
            type: string
            format: date-time
            description: Timestamp of when the integration was last synced
            example: '2023-05-15T10:30:00Z'
    IntegrationSyncFilters:
      type: object
      properties:
        group_prefixes:
          type: array
          description: List of start_with string patterns for groups to sync
          items:
            type: string
          example:
          - Engineering
          - Sales
        user_group_prefixes:
          type: array
          description: List of start_with string patterns for groups which users to sync
          items:
            type: string
          example:
          - Users
        connector_id:
          type: string
          description: DEX connector ID for embedded IDP setups
    IdpIntegrationSyncLog:
      type: object
      description: Represents a synchronization log entry for an integration
      required:
      - id
      - level
      - timestamp
      - message
      properties:
        id:
          type: integer
          format: int64
          description: The unique identifier for the sync log
          example: 123
        level:
          type: string
          description: The log level
          example: info
        timestamp:
          type: string
          format: date-time
          description: Timestamp of when the log was created
          example: '2023-05-15T10:30:00Z'
        message:
          type: string
          description: Log message
          example: Successfully synchronized users and groups
    CreateScimIntegrationRequest:
      allOf:
      - $ref: '#/components/schemas/IntegrationSyncFilters'
      - type: object
        description: Request payload for creating an SCIM IDP integration
        required:
        - prefix
        - provider
        properties:
          prefix:
            type: string
            description: The connection prefix used for the SCIM provider
          provider:
            type: string
            description: Name of the SCIM identity provider
    ErrorResponse:
      type: object
      description: 'Standard error response. Note: The exact structure of this error response is inferred from `util.WriteErrorResponse` and `util.WriteError` usage in the provided Go code, as a specific Go struct for errors was not provided.'
      properties:
        message:
          type: string
          description: A human-readable error message.
          example: couldn't parse JSON request
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Enter the token with the `Token` prefix, e.g. "Token nbp_F3f0d.....".