Tackle Users API

openapi: 3.0.3
info:
  title: Tackle Authentication Users API
  description: Authenticated programmatic access to Tackle's webhooks, metering, private offers, and more.
  version: 1.0.0
  contact:
    name: Tackle Support
    email: support@tackle.io
    url: https://tackle.io
servers:
- url: https://api.tackle.io
tags:
- name: Users
  description: User management operations
paths:
  /scim/v2/Users:
    get:
      tags:
      - Users
      summary: List Users
      description: 'Retrieve a list of users. Supports pagination through startIndex and count parameters.

        '
      operationId: getUsers
      parameters:
      - name: startIndex
        in: query
        description: The 1-based index of the first result in the current set of results
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: count
        in: query
        description: Maximum number of results to return
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: filter
        in: query
        description: SCIM filter expression
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
              example:
                schemas:
                - urn:ietf:params:scim:api:messages:2.0:ListResponse
                totalResults: 2
                itemsPerPage: 2
                startIndex: 1
                Resources:
                - schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:User
                  - urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
                  id: user123
                  userName: john.doe@example.com
                  displayName: John Doe
                  active: true
                  name:
                    givenName: John
                    familyName: Doe
                  emails:
                  - value: john.doe@example.com
                    primary: true
                    type: work
                  meta:
                    resourceType: User
                    created: '2024-01-15T10:30:00Z'
                    lastModified: '2024-01-15T10:30:00Z'
                    location: https://scim-api.tackle.io/scim/v2/Users/user123
                  urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
                    employeeNumber: '12345'
                    organization: Tackle
                    division: Engineering
                    department: Platform
                    manager:
                      value: manager456
        '400':
          description: Bad request - invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Users
      summary: Create User
      description: 'Create a new user. The user will be created in Auth0 SCIM and then have

        their metadata updated with organization information.

        '
      operationId: createUser
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/UserInput'
            example:
              schemas:
              - urn:ietf:params:scim:schemas:core:2.0:User
              - urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
              userName: jane.smith@example.com
              displayName: Jane Smith
              active: true
              name:
                givenName: Jane
                familyName: Smith
              emails:
              - value: jane.smith@example.com
                primary: true
                type: work
              urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
                employeeNumber: '54321'
                organization: Tackle
                division: Sales
                department: Enterprise
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request - invalid user data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Conflict - user already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
              example:
                schemas:
                - urn:ietf:params:scim:api:messages:2.0:Error
                status: '409'
                detail: User with userName jane.smith@example.com already exists
                scimType: uniqueness
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /scim/v2/Users/{id}:
    get:
      tags:
      - Users
      summary: Get User by ID
      description: Retrieve a specific user by their unique identifier.
      operationId: getUserById
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier for the user
        schema:
          type: string
          example: user123
      responses:
        '200':
          description: User retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request - invalid user ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
              example:
                schemas:
                - urn:ietf:params:scim:api:messages:2.0:Error
                status: '404'
                detail: User user123 not found
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Users
      summary: Update User
      description: 'Update an existing user. This performs a full replacement of the user resource.

        '
      operationId: updateUser
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier for the user
        schema:
          type: string
          example: user123
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/UserInput'
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request - invalid user data or ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
      - Users
      summary: Patch User
      description: 'Perform a partial update of a user using SCIM PATCH operations.

        Supports operations like updating user roles (entitlements), active status, and other attributes.


        Common use cases:

        - Update user role by patching entitlements

        - Deactivate a user (clears vendorid and role in metadata)

        - Reactivate a user (restores vendorid from organization data)

        '
      operationId: patchUser
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier for the user
        schema:
          type: string
          example: user123
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/PatchOp'
            example:
              schemas:
              - urn:ietf:params:scim:api:messages:2.0:PatchOp
              Operations:
              - op: replace
                path: active
                value: false
          application/json:
            schema:
              $ref: '#/components/schemas/PatchOp'
            example:
              schemas:
              - urn:ietf:params:scim:api:messages:2.0:PatchOp
              Operations:
              - op: replace
                path: entitlements
                value:
                - value: admin_role_id
                  type: role
      responses:
        '200':
          description: User patched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request - invalid patch operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Users
      summary: Delete User
      description: 'Soft-delete a user. Per SCIM 2.0 (RFC 7644 §3.6) this returns 204 No

        Content on success. Internally the user is deactivated (active=false)

        and the vendorid/role app_metadata are cleared so the user can no

        longer access Tackle resources. The underlying Auth0 user record is

        preserved so SSO logins can be re-authorized if the user is later

        re-provisioned, and so identity providers that probe DELETE during

        their connection-test lifecycle (e.g. JumpCloud) can complete

        activation without permanently destroying the test user.

        '
      operationId: deleteUser
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier for the user
        schema:
          type: string
          example: user123
      responses:
        '204':
          description: User soft-deleted successfully (no response body)
        '400':
          description: Bad request - invalid userID path parameter or SCIM integration not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Photo:
      type: object
      required:
      - type
      - value
      properties:
        type:
          type: string
          description: Type of photo
          example: photo
        value:
          type: string
          format: uri
          description: URL to the photo
          example: https://example.com/photo.jpg
    EnterpriseUser:
      type: object
      properties:
        employeeNumber:
          type: string
          description: Employee number
          example: '12345'
        organization:
          type: string
          description: Organization name
          example: Tackle
        division:
          type: string
          description: Division within the organization
          example: Engineering
        department:
          type: string
          description: Department within the organization
          example: Platform
        manager:
          $ref: '#/components/schemas/Manager'
    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
    UserListResponse:
      type: object
      required:
      - schemas
      - totalResults
      - itemsPerPage
      - startIndex
      - 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 results
          example: 100
        itemsPerPage:
          type: integer
          description: Number of results per page
          example: 50
        startIndex:
          type: integer
          description: 1-based index of the first result
          example: 1
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/User'
    UserInput:
      type: object
      required:
      - schemas
      - userName
      - name
      - emails
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
          - urn:ietf:params:scim:schemas:core:2.0:User
          - urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
        externalId:
          type: string
          description: External identifier for the user
          example: ext_user_456
        userName:
          type: string
          description: Unique username for the user
          example: john.doe@example.com
        displayName:
          type: string
          description: Display name for the user
          example: John Doe
        nickName:
          type: string
          description: Nickname for the user
          example: Johnny
        title:
          type: string
          description: Job title
          example: Senior Engineer
        active:
          type: boolean
          description: Whether the user is active
          example: true
        locale:
          type: string
          description: User's preferred locale
          example: en-US
        name:
          $ref: '#/components/schemas/Name'
        emails:
          type: array
          items:
            $ref: '#/components/schemas/Email'
        photos:
          type: array
          items:
            $ref: '#/components/schemas/Photo'
        urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
          $ref: '#/components/schemas/EnterpriseUser'
    PatchOperation:
      type: object
      required:
      - op
      properties:
        op:
          type: string
          description: The operation to perform
          enum:
          - add
          - remove
          - replace
          example: replace
        path:
          type: string
          description: The attribute path to modify
          example: active
        value:
          description: The value for the operation (type varies by operation and path)
          oneOf:
          - type: string
          - type: boolean
          - type: integer
          - type: object
          - type: array
    Email:
      type: object
      required:
      - value
      - primary
      properties:
        value:
          type: string
          format: email
          description: Email address
          example: john.doe@example.com
        type:
          type: string
          description: Type of email address
          example: work
        primary:
          type: boolean
          description: Whether this is the primary email
          example: true
    Meta:
      type: object
      readOnly: true
      properties:
        resourceType:
          type: string
          description: The resource type
          example: User
        created:
          type: string
          format: date-time
          description: When the resource was created
          example: '2024-01-15T10:30:00Z'
        lastModified:
          type: string
          format: date-time
          description: When the resource was last modified
          example: '2024-01-15T10:30:00Z'
        location:
          type: string
          format: uri
          description: URL to the resource
          example: https://scim-api.tackle.io/scim/v2/Users/user123
    Manager:
      type: object
      required:
      - value
      properties:
        value:
          type: string
          description: Manager's user ID
          example: manager456
    PatchOp:
      type: object
      required:
      - schemas
      - Operations
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
          - urn:ietf:params:scim:api:messages:2.0:PatchOp
        Operations:
          type: array
          items:
            $ref: '#/components/schemas/PatchOperation'
          description: List of patch operations to perform
    User:
      type: object
      required:
      - schemas
      - userName
      - name
      - emails
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
          - urn:ietf:params:scim:schemas:core:2.0:User
          - urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
        id:
          type: string
          readOnly: true
          description: Unique identifier for the user
          example: user123
        externalId:
          type: string
          description: External identifier for the user
          example: ext_user_456
        userName:
          type: string
          description: Unique username for the user
          example: john.doe@example.com
        displayName:
          type: string
          description: Display name for the user
          example: John Doe
        nickName:
          type: string
          description: Nickname for the user
          example: Johnny
        title:
          type: string
          description: Job title
          example: Senior Engineer
        active:
          type: boolean
          description: Whether the user is active
          example: true
        locale:
          type: string
          description: User's preferred locale
          example: en-US
        name:
          $ref: '#/components/schemas/Name'
        emails:
          type: array
          items:
            $ref: '#/components/schemas/Email'
        photos:
          type: array
          items:
            $ref: '#/components/schemas/Photo'
        meta:
          $ref: '#/components/schemas/Meta'
        urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
          $ref: '#/components/schemas/EnterpriseUser'
    Name:
      type: object
      required:
      - givenName
      - familyName
      properties:
        givenName:
          type: string
          description: First name
          example: John
        familyName:
          type: string
          description: Last name
          example: Doe
  responses:
    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
    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
  securitySchemes:
    BearerAuth:
      description: The Tackle API requires a JWT for authentication. You can get this by [getting your API credentials](https://developers.tackle.io/docs/how-to-get-an-m2m-client-id-and-secret) from the Tackle Platform then [retrieving your Access Token](https://developers.tackle.io/docs/getting-an-access-token) using our Authentication endpoint.
      type: http
      scheme: bearer
      bearerFormat: JWT
    BasicAuthCallback:
      description: Use `basic` for [basic HTTP authentication](https://en.wikipedia.org/wiki/Basic_access_authentication); this is only used for `callbacks`
      type: http
      scheme: basic
    HeaderApiKeyAuthCallback:
      description: Use `header_api_key` to specify a custom HTTP request header for authentication. Requests from Tackle will use the specified HTTP header for outbound requests to your Webhook URL; this is only used for `callbacks`'
      type: apiKey
      name: subscription-key
      in: header
    Oauth2AuthCallback:
      description: This auth-type is for `oauth2` client credentials flow. We will use the client_id and client_secret to call the token_url to get an access token; this is only used for `callbacks`'
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
externalDocs:
  description: Tackle Developer Hub and API Documentation
  url: https://developers.tackle.io
x-readme:
  explorer-enabled: false
  proxy-enabled: true
  samples-enabled: true