NetBird IDP Google Integrations API

openapi: 3.1.0
info:
  title: NetBird REST Accounts IDP Google 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 Google Integrations
  description: Manage Google Workspace identity provider integrations for user and group sync.
  x-cloud-only: true
paths:
  /api/integrations/google-idp:
    post:
      tags:
      - IDP Google Integrations
      summary: Create Google IDP Integration
      description: Creates a new Google Workspace IDP integration
      operationId: createGoogleIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGoogleIntegrationRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleIntegration'
        '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 Google Integrations
      summary: Get All Google IDP Integrations
      description: Retrieves all Google Workspace IDP integrations for the authenticated account
      operationId: getAllGoogleIntegrations
      responses:
        '200':
          description: A list of Google IDP integrations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GoogleIntegration'
        '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/google-idp/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: The unique identifier of the Google IDP integration.
      schema:
        type: integer
        format: int64
        example: 1
    get:
      tags:
      - IDP Google Integrations
      summary: Get Google IDP Integration
      description: Retrieves a Google IDP integration by ID.
      operationId: getGoogleIntegration
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleIntegration'
        '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 Google Integrations
      summary: Update Google IDP Integration
      description: Updates an existing Google Workspace IDP integration.
      operationId: updateGoogleIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGoogleIntegrationRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleIntegration'
        '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 Google Integrations
      summary: Delete Google IDP Integration
      description: Deletes a Google IDP integration by ID.
      operationId: deleteGoogleIntegration
      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/google-idp/{id}/sync:
    parameters:
    - name: id
      in: path
      required: true
      description: The unique identifier of the Google IDP integration.
      schema:
        type: integer
        format: int64
        example: 1
    post:
      tags:
      - IDP Google Integrations
      summary: Sync Google IDP Integration
      description: Triggers a manual synchronization for a Google IDP integration.
      operationId: syncGoogleIntegration
      responses:
        '200':
          description: Sync triggered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncResult'
        '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/google-idp/{id}/logs:
    parameters:
    - name: id
      in: path
      required: true
      description: The unique identifier of the Google IDP integration.
      schema:
        type: integer
        format: int64
        example: 1
    get:
      tags:
      - IDP Google Integrations
      summary: Get Google Integration Sync Logs
      description: Retrieves synchronization logs for a Google IDP integration.
      operationId: getGoogleIntegrationLogs
      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:
    UpdateGoogleIntegrationRequest:
      allOf:
      - $ref: '#/components/schemas/IntegrationEnabled'
      - $ref: '#/components/schemas/IntegrationSyncFilters'
      - type: object
        description: Request payload for updating a Google Workspace IDP integration. All fields are optional.
        properties:
          service_account_key:
            type: string
            description: Base64-encoded Google service account key
          customer_id:
            type: string
            description: Customer ID from Google Workspace Account Settings
          sync_interval:
            type: integer
            description: Sync interval in seconds (minimum 300)
            minimum: 300
    IntegrationEnabled:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether the integration is enabled
          example: true
    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
    GoogleIntegration:
      allOf:
      - $ref: '#/components/schemas/IntegrationEnabled'
      - $ref: '#/components/schemas/IntegrationSyncFilters'
      - type: object
        description: Represents a Google Workspace IDP integration
        required:
        - id
        - customer_id
        - sync_interval
        - enabled
        - group_prefixes
        - user_group_prefixes
        - last_synced_at
        properties:
          id:
            type: integer
            format: int64
            description: The unique identifier for the integration
            example: 1
          customer_id:
            type: string
            description: Customer ID from Google Workspace
            example: C01234567
          sync_interval:
            type: integer
            description: Sync interval in seconds
            example: 300
          last_synced_at:
            type: string
            format: date-time
            description: Timestamp of the last synchronization
            example: '2023-05-15T10:30:00Z'
    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
    SyncResult:
      type: object
      description: Response for a manual sync trigger
      properties:
        result:
          type: string
          example: ok
    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
    CreateGoogleIntegrationRequest:
      allOf:
      - $ref: '#/components/schemas/IntegrationSyncFilters'
      - type: object
        description: Request payload for creating a Google Workspace IDP integration
        required:
        - service_account_key
        - customer_id
        properties:
          service_account_key:
            type: string
            description: Base64-encoded Google service account key
            example: eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii...
          customer_id:
            type: string
            description: Customer ID from Google Workspace Account Settings
            example: C01234567
          sync_interval:
            type: integer
            description: Sync interval in seconds (minimum 300). Defaults to 300 if not specified.
            minimum: 300
            example: 300
  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.....".