Tackle.io Groups API

openapi: 3.0.3
info:
  title: Tackle Public Contracts Authentication Groups API
  description: "Customer-facing read API for cloud marketplace contracts that Tackle has\ningested for your Tackle account.\n\nThe response shape is a stable projection of the underlying\ncontract document. It is intended to be safe to consume long-term: fields\nwill be added over time, but documented fields will not be removed without\ndeprecation notice.\n\n## Authentication\n\nEvery request must include a valid Tackle JWT in the `Authorization`\nheader (`Authorization: Bearer <token>`). Machine-to-machine (MTM) tokens\nissued for your Tackle account are accepted. The token scopes every\nresponse to the account it represents.\n\n## Pagination\n\n`GET /api/contracts` is the only paginated endpoint. Pagination uses an\nopaque `cursor` query parameter:\n\n1. The first request omits `cursor`.\n2. If more pages exist, the response includes a `next` field. Pass that\n   value verbatim back as `cursor` on the next request.\n3. The last page omits `next`.\n\nCursors are opaque tokens. Do not parse, modify, or persist them across\nschema changes — request a fresh page from the start instead.\n"
  version: 1.0.0
servers:
- url: https://contracts.tackle.io
  description: Production
security:
- tackleJwt: []
tags:
- name: Groups
  description: SCIM 2.0 Groups endpoint - returns full Group resources (RFC 7643 §4.2)
paths:
  /scim/v2/Groups:
    get:
      tags:
      - Groups
      summary: Get Groups
      description: 'Retrieve available groups (roles) for the organization.

        This is the standard SCIM 2.0 Groups endpoint per RFC 7644.

        It fetches roles from the RBAC service and returns them as SCIM Group resources

        with meta.resourceType set to "Group", as required by identity providers (Okta, Azure AD).

        '
      operationId: getGroups
      responses:
        '200':
          description: Groups retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupListResponse'
              example:
                schemas:
                - urn:ietf:params:scim:api:messages:2.0:ListResponse
                totalResults: 3
                startIndex: 1
                itemsPerPage: 3
                Resources:
                - schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:Group
                  id: role_admin_123
                  displayName: Administrator
                  meta:
                    resourceType: Group
                    location: https://scim-api.tackle.io/scim/v2/Groups/role_admin_123
                  members: []
                - schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:Group
                  id: role_user_456
                  displayName: User
                  meta:
                    resourceType: Group
                    location: https://scim-api.tackle.io/scim/v2/Groups/role_user_456
                  members: []
                - schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:Group
                  id: role_viewer_789
                  displayName: Viewer
                  meta:
                    resourceType: Group
                    location: https://scim-api.tackle.io/scim/v2/Groups/role_viewer_789
                  members: []
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ScimError:
      type: object
      required:
      - schemas
      - status
      - detail
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
          - urn:ietf:params:scim:api:messages:2.0:Error
        status:
          type: string
          description: HTTP status code as string
          example: '400'
        detail:
          type: string
          description: Human-readable error description
          example: Invalid request
        scimType:
          type: string
          description: SCIM-specific error type
          enum:
          - invalidFilter
          - tooMany
          - uniqueness
          - mutability
          - invalidSyntax
          - invalidPath
          - noTarget
          - invalidValue
          - invalidVers
          - sensitive
          example: invalidValue
    Group:
      type: object
      required:
      - schemas
      - id
      - displayName
      - meta
      - members
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
          - urn:ietf:params:scim:schemas:core:2.0:Group
        id:
          type: string
          description: The unique identifier of the group (role ID)
          example: role_admin_123
        displayName:
          type: string
          description: The display name of the group (role name)
          example: Administrator
        meta:
          type: object
          required:
          - resourceType
          - location
          properties:
            resourceType:
              type: string
              description: Always "Group" for this resource type
              example: Group
            location:
              type: string
              format: uri
              description: URL to this group resource
              example: https://scim-api.tackle.io/scim/v2/Groups/role_admin_123
        members:
          type: array
          description: Group members (always empty; membership is managed via user entitlements)
          items:
            type: string
          example: []
    GroupListResponse:
      type: object
      required:
      - schemas
      - totalResults
      - startIndex
      - itemsPerPage
      - Resources
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
          - urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults:
          type: integer
          description: Total number of groups
          example: 3
        startIndex:
          type: integer
          description: 1-based index of the first result
          example: 1
        itemsPerPage:
          type: integer
          description: Number of groups in this response
          example: 3
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/Group'
  responses:
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScimError'
          example:
            schemas:
            - urn:ietf:params:scim:api:messages:2.0:Error
            status: '500'
            detail: Internal server error
    Unauthorized:
      description: Authentication information is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScimError'
          example:
            schemas:
            - urn:ietf:params:scim:api:messages:2.0:Error
            status: '401'
            detail: Unauthorized
    Forbidden:
      description: Access forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScimError'
          example:
            schemas:
            - urn:ietf:params:scim:api:messages:2.0:Error
            status: '403'
            detail: Forbidden
  securitySchemes:
    tackleJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Tackle-issued JWT (interactive user or MTM token).