Tackle SCIM API Documentation

Overview

The Tackle SCIM (System for Cross-domain Identity Management) API enables automated user provisioning and lifecycle management. This API implements the SCIM 2.0 protocol (RFC 7644), allowing identity providers and enterprise systems to automatically create, update, and manage users in the Tackle platform.

Getting Started

Base URL

All API requests should be made to:

https://scim.tackle.io

Prerequisites

Before using the SCIM API, you will need:

1. An active Tackle organization account
2. An API key for authentication

Obtaining Your API Key

To request an API key for your organization, please contact Tackle Support at [email protected].

Our Ssupport team will provision an API key for your organization and provide it securely.

Authentication

The SCIM API uses API key authentication. Include your API key in the Authorization header of every request:

Authorization: <your-api-key>

Example:

curl -X GET https://scim.tackle.io/scim/v2/Users \
  -H "Authorization: scim_live_abcd1234efgh5678"

Rate Limits

The API enforces a rate limit of 1,000 transactions per second (TPS) per organization.

User Management

User Resource Schema

Users follow the SCIM 2.0 Core User schema (urn:ietf:params:scim:schemas:core:2.0:User).

Required Fields:

• schemas - Array of schema URNs
• userName - Unique identifier (typically email address)
• name.givenName - First name
• name.familyName - Last name
• emails - Array with at least one email object
• externalId - External identifier from your system

Optional Fields:

• displayName - Display name for the user
• active - Boolean indicating if user is active (default: true)
• nickName - User’s nickname
• title - Job title
• locale - User’s preferred locale (e.g., “en-US”)
• photos - Array of photo objects

Create User

Create a new user in Tackle.

Endpoint: POST /scim/v2/Users

Request Headers:

Authorization: <your-api-key>
Content-Type: application/scim+json

Request Body:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "[email protected]",
  "externalId": "jane.smith",
  "name": {
    "givenName": "Jane",
    "familyName": "Smith"
  },
  "emails": [
    {
      "value": "[email protected]",
      "primary": true,
      "type": "work"
    }
  ],
  "displayName": "Jane Smith",
  "active": true,
  "title": "Software Engineer"
}

Response: 201 Created

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "okta|sso-okta-example-com|jane.smith",
    "externalId": "jane.smith",
    "userName": "[email protected]",
    "displayName": "Jane Smith",
    "nickName": "jane.smith",
    "title": "Software Engineer",
    "active": true,
    "name": {
        "givenName": "Jane",
        "familyName": "Smith"
    },
    "emails": [
        {
            "primary": true,
            "value": "[email protected]"
        }
    ],
    "photos": [
        {
            "type": "photo",
            "value": "https://s.gravatar.com/avatar/5ca5d412e374a647e0fd670e815ed299?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fjs.png"
        }
    ],
    "entitlements": [
        {
            "value": ""
        }
    ],
    "meta": {
        "resourceType": "User",
        "created": "2025-12-02T16:42:38.206Z",
        "lastModified": "2025-12-02T16:42:38.206Z",
        "location": "/scim/v2/connections/con_SnLtLvfQoutiIGSh/Users/okta%7Csso-okta-adstage-salesforce-com%7Cjane.smith"
    }
}

cURL Example:

curl -X POST https://scim.tackle.io/scim/v2/Users \
  -H "Authorization: scim_live_abcd1234efgh5678" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "externalId": "jane.smith",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "emails": [
      {
        "value": "[email protected]",
        "primary": true
      }
    ],
    "displayName": "Jane Smith",
    "active": true
  }'

Get User by ID

Retrieve a specific user by their unique identifier.

Endpoint: GET /scim/v2/Users/{id}

Path Parameters: - id - The unique user identifier (URL-encoded)

Request Headers:

Authorization: <your-api-key>

Response: 200 OK

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "samlp|example|jane.smith",
  "userName": "[email protected]",
  "name": {
    "givenName": "Jane",
    "familyName": "Smith"
  },
  "emails": [
    {
      "value": "[email protected]",
      "primary": true,
      "type": "work"
    }
  ],
  "displayName": "Jane Smith",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2024-01-15T10:30:00Z",
    "lastModified": "2024-01-15T10:30:00Z",
    "location": "https://scim.tackle.io/scim/v2/Users/samlp%7Cexample%7Cjane.smith"
  }
}

cURL Example:

curl -X GET "https://scim.tackle.io/scim/v2/Users/samlp%7Cexample%7Cjane.smith" \
  -H "Authorization: scim_live_abcd1234efgh5678"

Note: User IDs must be URL-encoded. For example, samlp|example|jane.smith becomes samlp%7Cexample%7Cjane.smith.

List Users

Retrieve a paginated list of users for your organization.

Endpoint: GET /scim/v2/Users

Query Parameters:

• startIndex (optional) - 1-based index of the first result (default: 1, minimum: 1)
• count (optional) - Maximum number of results to return (default: 50, maximum: 100)
• filter (optional) - SCIM filter expression syntax, as defined in RFC 7644 Section 3.4.2.2

Example: to filter for active users, ?filter=active eq true

Request Headers:

Authorization: <your-api-key>

Response: 200 OK

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 150,
  "itemsPerPage": 50,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "samlp|example|jane.smith",
      "userName": "[email protected]",
      "name": {
        "givenName": "Jane",
        "familyName": "Smith"
      },
      "emails": [
        {
          "value": "[email protected]",
          "primary": true
        }
      ],
      "displayName": "Jane Smith",
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2024-01-15T10:30:00Z",
        "lastModified": "2024-01-15T10:30:00Z",
        "location": "https://scim.tackle.io/scim/v2/Users/samlp%7Cexample%7Cjane.smith"
      }
    }
  ]
}

cURL Example:

# Get first 50 users
curl -X GET "https://scim.tackle.io/scim/v2/Users" \
  -H "Authorization: scim_live_abcd1234efgh5678"

# Get next page (51-100)
curl -X GET "https://scim.tackle.io/scim/v2/Users?startIndex=51&count=50" \
  -H "Authorization: scim_live_abcd1234efgh5678"

Update User (PATCH)

Partially update an existing user using PATCH operations. This is the recommended method for updating user attributes, activating/deactivating users, and managing roles.

Endpoint: PATCH /scim/v2/Users/{id}

Path Parameters:

• id - The unique user identifier (URL-encoded)

Request Headers:

Authorization: <your-api-key>
Content-Type: application/scim+json

Supported Operations:

• add - Add a new value to an attribute
• replace - Replace an existing attribute value
• remove - Remove an attribute value

Supported Paths:

• active - Activate or deactivate a user
• displayName - Update display name
• name - Update name (givenName, familyName)
• entitlements - Update user roles/permissions

Update Display Name

Request Body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "Jane Doe-Smith"
    }
  ]
}

cURL Example:

curl -X PATCH "https://scim.tackle.io/scim/v2/Users/samlp%7Cexample%7Cjane.smith" \
  -H "Authorization: scim_live_abcd1234efgh5678" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "displayName",
        "value": "Jane Doe-Smith"
      }
    ]
  }'

Update Name

Request Body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "name",
      "value": {
        "givenName": "Jane",
        "familyName": "Doe-Smith"
      }
    }
  ]
}

Deactivate User

Deactivate a user account. Deactivated users cannot log in to Tackle.

Request Body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": false
    }
  ]
}

cURL Example:

curl -X PATCH "https://scim.tackle.io/scim/v2/Users/samlp%7Cexample%7Cjane.smith" \
  -H "Authorization: scim_live_abcd1234efgh5678" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "active",
        "value": false
      }
    ]
  }'

Reactivate User

Reactivate a previously deactivated user account.

Request Body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": true
    }
  ]
}

cURL Example:

curl -X PATCH "https://scim.tackle.io/scim/v2/Users/samlp%7Cexample%7Cjane.smith" \
  -H "Authorization: scim_live_abcd1234efgh5678" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "active",
        "value": true
      }
    ]
  }'

Assign Role/Entitlement

Assign a role or entitlement to a user.

Request Body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "entitlements",
      "value": [
        {
          "value": "admin"
        }
      ]
    }
  ]
}

cURL Example:

curl -X PATCH "https://scim.tackle.io/scim/v2/Users/samlp%7Cexample%7Cjane.smith" \
  -H "Authorization: scim_live_abcd1234efgh5678" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "entitlements",
        "value": [
          {
            "value": "admin"
          }
        ]
      }
    ]
  }'

Remove Role/Entitlement

Remove a user’s role or entitlement.

Request Body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "entitlements"
    }
  ]
}

Multiple Operations

You can include multiple operations in a single PATCH request:

Request Body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": true
    },
    {
      "op": "replace",
      "path": "displayName",
      "value": "Jane Smith"
    },
    {
      "op": "replace",
      "path": "entitlements",
      "value": [
        {
          "value": "admin"
        }
      ]
    }
  ]
}

Response: 200 OK

Returns the updated user object (same format as Get User by ID).

Update User (PUT)

Replace an entire user resource. This performs a full update where all fields are replaced.

Endpoint: PUT /scim/v2/Users/{id}

Path Parameters: - id - The unique user identifier (URL-encoded)

Request Headers:

Authorization: <your-api-key>
Content-Type: application/scim+json

Request Body:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "[email protected]",
  "name": {
    "givenName": "Jane",
    "familyName": "Smith"
  },
  "emails": [
    {
      "value": "[email protected]",
      "primary": true
    }
  ],
  "displayName": "Jane Smith",
  "active": true
}

Response: 200 OK

Returns the updated user object.

Note: PATCH is generally preferred over PUT for partial updates as it’s more efficient and reduces the risk of unintentionally clearing fields.

Service Provider Endpoints

These endpoints provide metadata about the SCIM implementation and its capabilities.

Get Service Provider Configuration

Retrieve information about the SCIM service provider’s capabilities.

Endpoint: GET /scim/v2/ServiceProviderConfig

Request Headers:

Authorization: <your-api-key>

Response: 200 OK

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "patch": {
    "supported": true
  },
  "bulk": {
    "supported": false,
    "maxPayloadSize": 5242880,
    "maxOperations": 1
  },
  "filter": {
    "supported": false,
    "maxResults": 100
  },
  "changePassword": {
    "supported": false
  },
  "sort": {
    "supported": false
  },
  "etag": {
    "supported": false
  },
  "authenticationSchemes": [
    {
      "type": "oauthbearertoken",
      "name": "OAuth Bearer Token",
      "description": "Authentication scheme using the OAuth Bearer Token Standard",
      "specUri": "http://www.rfc-editor.org/info/rfc6750",
      "primary": true
    }
  ],
  "pagination": {
    "cursor": false,
    "index": true,
    "defaultPaginationMethod": "index",
    "defaultPageSize": 50,
    "maxPageSize": 100
  },
  "meta": {
    "resourceType": "ServiceProviderConfig",
    "created": "2025-06-12T00:00:00Z",
    "lastModified": "2025-06-12T00:00:00Z",
    "location": "https://scim.tackle.io/scim/v2/ServiceProviderConfig"
  }
}

cURL Example:

curl -X GET https://scim.tackle.io/scim/v2/ServiceProviderConfig \
  -H "Authorization: scim_live_abcd1234efgh5678"

Get Resource Types

Retrieve the resource types supported by the SCIM implementation.

Endpoint: GET /scim/v2/ResourceTypes

Request Headers:

Authorization: <your-api-key>

Response: 200 OK

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "itemsPerPage": 1,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
      "id": "User",
      "name": "User",
      "endpoint": "https://scim.tackle.io/scim/v2/Users",
      "description": "User Account",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "meta": {
        "location": "https://scim.tackle.io/scim/v2/ResourceTypes/User"
      }
    }
  ]
}

cURL Example:

curl -X GET https://scim.tackle.io/scim/v2/ResourceTypes \
  -H "Authorization: scim_live_abcd1234efgh5678"

Get Schemas

Retrieve the schemas supported by the SCIM implementation.

Endpoint: GET /scim/v2/Schemas

Request Headers:

Authorization: <your-api-key>

Response: 200 OK

Returns detailed schema definitions for User resources including attribute names, types, mutability, and constraints.

cURL Example:

curl -X GET https://scim.tackle.io/scim/v2/Schemas \
  -H "Authorization: scim_live_abcd1234efgh5678"

Error Handling

The API returns standard SCIM 2.0 error responses following RFC 7644.

Error Response Format

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "404",
  "detail": "User samlp|example|notfound not found"
}

Common Error Codes

Example Error Responses

Invalid Request Body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "400",
  "detail": "userName is required",
  "scimType": "invalidValue"
}

User Not Found:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "404",
  "detail": "User samlp|example|jane.smith not found"
}

Duplicate User:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "detail": "User with userName [email protected] already exists",
  "scimType": "uniqueness"
}

Unauthorized:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "401",
  "detail": "Unauthorized"
}

Integration with Identity Providers

The Tackle SCIM API is designed to work seamlessly with enterprise identity providers that support SCIM 2.0.

Supported Identity Providers

The API has been tested with the following identity providers: - Okta (Workforce Identity Cloud) - Microsoft Entra ID (formerly Azure AD) - Generic SCIM 2.0 clients

Configuration Parameters

When configuring SCIM in your identity provider, use these values:

Typical Provisioning Flow

1. Initial Sync: Identity provider creates users via POST /scim/v2/Users
2. User Updates: Changes to user attributes trigger PATCH /scim/v2/Users/{id} requests
3. User Deactivation: When users leave the organization, identity provider sends PATCH with active: false
4. User Reactivation: When users rejoin, identity provider sends PATCH with active: true

Common Use Cases

Use Case 1: Onboard a New Employee

When a new employee joins your organization:

1. Create the user account:

curl -X POST https://scim.tackle.io/scim/v2/Users \
  -H "Authorization: scim_live_abcd1234efgh5678" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "externalId": "john.doe",
    "name": {
      "givenName": "John",
      "familyName": "Doe"
    },
    "emails": [
      {
        "value": "[email protected]",
        "primary": true
      }
    ],
    "displayName": "John Doe",
    "active": true,
    "title": "Software Engineer"
  }'

2. Assign role (if needed):

curl -X PATCH "https://scim.tackle.io/scim/v2/Users/{userId}" \
  -H "Authorization: scim_live_abcd1234efgh5678" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "entitlements",
        "value": [{"value": "admin"}]
      }
    ]
  }'

Use Case 2: Employee Name Change

When an employee’s name changes (e.g., marriage):

curl -X PATCH "https://scim.tackle.io/scim/v2/Users/{userId}" \
  -H "Authorization: scim_live_abcd1234efgh5678" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "name",
        "value": {
          "givenName": "Jane",
          "familyName": "Smith-Jones"
        }
      },
      {
        "op": "replace",
        "path": "displayName",
        "value": "Jane Smith-Jones"
      }
    ]
  }'

Use Case 3: Offboard an Employee

When an employee leaves the organization:

curl -X PATCH "https://scim.tackle.io/scim/v2/Users/{userId}" \
  -H "Authorization: scim_live_abcd1234efgh5678" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "active",
        "value": false
      }
    ]
  }'

Testing Your Integration

Step 1: Verify Authentication

Test that your API key works:

curl -X GET https://scim.tackle.io/scim/v2/ServiceProviderConfig \
  -H "Authorization: <your-api-key>"

Expected: 200 OK with service provider configuration

Step 2: Create a Test User

curl -X POST https://scim.tackle.io/scim/v2/Users \
  -H "Authorization: <your-api-key>" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "externalId": "test.user",
    "name": {
      "givenName": "Test",
      "familyName": "User"
    },
    "emails": [
      {
        "value": "[email protected]",
        "primary": true
      }
    ],
    "displayName": "Test User",
    "active": true
  }'

Expected: 201 Created with user object containing an id

Step 3: Retrieve the User

Using the id from Step 2:

curl -X GET "https://scim.tackle.io/scim/v2/Users/<user-id>" \
  -H "Authorization: <your-api-key>"

Expected: 200 OK with user object matching the created user

Step 4: Update the User

curl -X PATCH "https://scim.tackle.io/scim/v2/Users/<user-id>" \
  -H "Authorization: <your-api-key>" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "displayName",
        "value": "Updated Test User"
      }
    ]
  }'

Expected: 200 OK with updated user object

Step 5: Deactivate the User

curl -X PATCH "https://scim.tackle.io/scim/v2/Users/<user-id>" \
  -H "Authorization: <your-api-key>" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "active",
        "value": false
      }
    ]
  }'

Expected: 200 OK with user object showing active: false

Frequently Asked Questions

General Questions

Q: Is there a sandbox environment for testing?

A: Currently, https://scim.tackle.io is the only environment. We recommend creating test users with clearly identifiable names (e.g., test- prefix) during integration development.

Q: Can I use the same API key for multiple identity providers?

A: Each API key is tied to a specific organization. Contact [email protected] if you need multiple API keys for different use cases.

Q: How do I rotate my API key?

A: Contact [email protected] to request a new API key. Update your identity provider configuration with the new key before we revoke the old one.

User Management Questions

Q: What happens when I deactivate a user?

A: Deactivated users cannot log in to Tackle. Their data is preserved and they can be reactivated at any time.

Q: Can I permanently delete a user?

A: User deletion is not currently supported via the SCIM API. Deactivate users instead. Contact [email protected] if you need to permanently remove a user.

Q: What is the difference between userName and email?

A: userName is the unique identifier for the user (typically an email address). The emails array can contain multiple email addresses, but userName must be unique across all users.

Q: Are email addresses case-sensitive?

A: No, email addresses are treated as case-insensitive. [email protected] and [email protected] are considered the same user.

Technical Questions

Q: What SCIM version is supported?

A: We support SCIM 2.0 (RFC 7644).

Q: Do you support SCIM filtering?

A: Filtering is not currently supported. Use the list endpoint with pagination to retrieve all users and filter client-side.

Q: Is bulk provisioning supported?

A: Bulk operations are not supported. Create, update, or deactivate users individually via their respective endpoints.

Q: What is the maximum request/response size?

A: There is no enforced limit, but we recommend keeping requests under 1MB for optimal performance.

Q: Do you support webhooks or real-time notifications?

A: Webhooks are not currently supported. You may need to poll the list users endpoint periodically to detect changes.

Support and Resources

Getting Help

If you encounter issues or have questions:

• Email Support: [email protected]
• Subject Line: Include “SCIM API” in the subject for faster routing

When contacting Support, please include:

• Your organization name
• API endpoint being called
• Request/response examples (redact your API key)
• Error messages or status codes
• Timestamp of the issue