SCIM Provisioning

SCIM (System for Cross-domain Identity Management) 2.0 enables automated, real-time user provisioning from your identity provider. When you add, update, or remove a user in your directory (Okta, Azure AD, etc.), those changes automatically sync to TruthVouch.

Getting Started

1. Enable SCIM in TruthVouch

1. Go to Settings → Security → SCIM
2. Click Generate SCIM Token
3. Copy the SCIM Base URL and Bearer Token
4. Store these securely — you’ll need them in your identity provider

2. Configure in Your Identity Provider

Okta Example:

1. Go to Applications → [Your TruthVouch App] → Provisioning
2. Set SCIM Base URL: https://your-instance.truthvouch.com/api/v1/scim/{clientId}
   • Replace {clientId} with your TruthVouch client GUID (found in Settings → Organization)
3. Set API Token: (the Bearer token from TruthVouch)
4. Set Authentication: Bearer token
5. Enable Create Users, Update User Attributes, Deactivate Users

Azure AD Example:

1. Go to Enterprise Applications → [Your TruthVouch App] → Provisioning
2. Provisioning Mode: Automatic
3. Tenant URL: https://your-instance.truthvouch.com/api/v1/scim/{clientId}
   • Replace {clientId} with your TruthVouch client GUID (found in Settings → Organization)
4. Secret Token: (the Bearer token from TruthVouch)
5. Enable Deprovisioning (optional)

---

SCIM Endpoint Reference

All SCIM operations use the base URL: https://your-instance.truthvouch.com/api/v1/scim/{clientId}

Replace:

• your-instance with your TruthVouch instance (e.g., app, us-west, etc.)
• {clientId} with your organization’s client GUID

Authentication

Include your SCIM token in the Authorization header:

curl -X GET https://your-instance.truthvouch.com/api/v1/scim/{clientId}/Users \
  -H "Authorization: Bearer scim_token_here" \
  -H "Content-Type: application/scim+json"

List Users

GET /Users

curl -X GET 'https://your-instance.truthvouch.com/api/v1/scim/{clientId}/Users?count=10&startIndex=1' \
  -H "Authorization: Bearer scim_token_here"

Response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 25,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    {
      "id": "user-uuid",
      "userName": "[email protected]",
      "name": {
        "givenName": "John",
        "familyName": "Doe"
      },
      "emails": [
        {
          "value": "[email protected]",
          "primary": true
        }
      ],
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2024-03-15T10:30:00Z",
        "lastModified": "2024-03-15T10:30:00Z"
      }
    }
  ]
}

Get User by ID

GET /Users/{id}

curl -X GET https://your-instance.truthvouch.com/api/v1/scim/{clientId}/Users/user-uuid \
  -H "Authorization: Bearer scim_token_here"

Create User

POST /Users

curl -X POST https://your-instance.truthvouch.com/api/v1/scim/{clientId}/Users \
  -H "Authorization: Bearer scim_token_here" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "emails": [
      {
        "value": "[email protected]",
        "primary": true
      }
    ],
    "active": true
  }'

Response (201 Created):

{
  "id": "new-user-uuid",
  "userName": "[email protected]",
  "meta": {
    "resourceType": "User",
    "created": "2024-03-15T11:00:00Z"
  }
}

Update User

PATCH /Users/{id}

curl -X PATCH https://your-instance.truthvouch.com/api/v1/scim/{clientId}/Users/user-uuid \
  -H "Authorization: Bearer scim_token_here" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "name.givenName",
        "value": "Jane"
      }
    ]
  }'

Deactivate User

PATCH /Users/{id}

curl -X PATCH https://your-instance.truthvouch.com/api/v1/scim/{clientId}/Users/user-uuid \
  -H "Authorization: Bearer scim_token_here" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "active",
        "value": false
      }
    ]
  }'

Delete User

DELETE /Users/{id}

curl -X DELETE https://your-instance.truthvouch.com/api/v1/scim/{clientId}/Users/user-uuid \
  -H "Authorization: Bearer scim_token_here"

Response: 204 No Content

---

User Attributes

Supported user attributes in SCIM operations:

Attribute	Type	Required	Notes
userName	string	Yes	User email (must be unique)
name.givenName	string	No	First name
name.familyName	string	No	Last name
emails[].value	string	Yes	Email address
emails[].primary	boolean	No	Primary email (default: true)
active	boolean	No	User account active (default: true)
displayName	string	No	Display name

Custom Attributes

TruthVouch supports custom SCIM extensions for:

• department — User’s department
• organization — User’s organization/team
• roles — Assigned roles (array of strings)

Example:

{
  "userName": "[email protected]",
  "urn:truthvouch:params:scim:schemas:extension:1.0": {
    "department": "Engineering",
    "organization": "Platform",
    "roles": ["developer", "oncall"]
  }
}

---

Groups (Optional)

SCIM also supports group management for role-based access:

List Groups

GET /Groups

curl -X GET https://your-instance.truthvouch.com/api/v1/scim/{clientId}/Groups \
  -H "Authorization: Bearer scim_token_here"

Create Group

POST /Groups

curl -X POST https://your-instance.truthvouch.com/api/v1/scim/{clientId}/Groups \
  -H "Authorization: Bearer scim_token_here" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "Engineering Team",
    "members": [
      {
        "value": "user-uuid",
        "display": "[email protected]"
      }
    ]
  }'

---

Sync Behavior

How SCIM Sync Works

1. Identity Provider → TruthVouch (push mode)

   • Your identity provider (Okta, Azure AD, etc.) sends SCIM requests to TruthVouch
   • TruthVouch creates, updates, or deactivates users accordingly

2. Real-time sync

   • When you add a user in Okta, they appear in TruthVouch within seconds
   • When you change a user’s name, TruthVouch updates it immediately
   • When you deactivate a user, they lose access to TruthVouch

3. Idempotent operations

   • If the same user is provisioned twice, no duplicate is created
   • Updates can be applied multiple times safely

Frequency

• Real-time sync: Immediate (when actions occur in identity provider)
• Periodic sync: Configurable in your identity provider (e.g., every 1 hour)

---

Managing SCIM Tokens

Regenerate Token

If you suspect a SCIM token has been compromised:

1. Go to Settings → Security → SCIM
2. Click Regenerate Token
3. Update your identity provider with the new token
4. The old token is immediately invalidated

Revoke SCIM

To disable all SCIM provisioning:

1. Go to Settings → Security → SCIM
2. Click Disable SCIM
3. All SCIM tokens are invalidated
4. Manual user management resumes

---

Troubleshooting

”Invalid Bearer Token”

The SCIM token is missing, invalid, or expired.

Fix:

• Verify the token in your identity provider matches exactly
• Regenerate the token in Settings → Security → SCIM
• Update the identity provider with the new token

”User not found” (on update)

You’re trying to update a user that doesn’t exist in TruthVouch.

Fix:

• Check that the user was created first (GET /Users to list)
• Verify the user ID is correct

”Email already in use”

A user with that email already exists.

Fix:

• Use the PATCH operation to update the existing user
• Or delete the old user first (if duplicated)

“Invalid user attributes”

One or more required attributes are missing.

Fix:

• Verify userName and emails[].value are both provided
• userName must be a valid email address

Sync Failures in Identity Provider

The identity provider shows SCIM sync errors.

Fix:

1. Verify the SCIM base URL is correct: https://your-instance.truthvouch.com/api/v1/scim/{clientId}
   • Replace placeholders with your actual instance and client ID
2. Verify the Bearer token is valid and hasn’t been regenerated
3. Check the identity provider’s sync logs for detailed error messages
4. Test manually via curl before re-enabling auto-sync

---

Best Practices

1. Enable before bulk import: Set up SCIM before adding many users, so they’re automatically provisioned
2. Test with one user first: Create one test user manually, then enable SCIM for others
3. Rotate SCIM tokens quarterly: Regenerate your SCIM token every 90 days
4. Use deprovisioning: Enable automatic deactivation when users leave the organization
5. Monitor sync logs: Regularly check your identity provider’s sync logs for errors

---

Next Steps

• OAuth / SSO Setup →
• API Keys →
• User Management →
• API Reference →