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://api.truthvouch.com/scim/v2
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://api.truthvouch.com/scim/v2
4. Secret Token: (the Bearer token from TruthVouch)
5. Enable Deprovisioning (optional)

---

SCIM Endpoint Reference

All SCIM operations use the base URL: https://api.truthvouch.com/scim/v2

Authentication

Include your SCIM token in the Authorization header:

curl -X GET https://api.truthvouch.com/scim/v2/Users \
  -H "Authorization: Bearer scim_token_here" \
  -H "Content-Type: application/scim+json"

List Users

GET /Users

curl -X GET 'https://api.truthvouch.com/scim/v2/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": "john.doe@company.com",
      "name": {
        "givenName": "John",
        "familyName": "Doe"
      },
      "emails": [
        {
          "value": "john.doe@company.com",
          "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://api.truthvouch.com/scim/v2/Users/user-uuid \
  -H "Authorization: Bearer scim_token_here"

Create User

POST /Users

curl -X POST https://api.truthvouch.com/scim/v2/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": "jane.smith@company.com",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "emails": [
      {
        "value": "jane.smith@company.com",
        "primary": true
      }
    ],
    "active": true
  }'

Response (201 Created):

{
  "id": "new-user-uuid",
  "userName": "jane.smith@company.com",
  "meta": {
    "resourceType": "User",
    "created": "2024-03-15T11:00:00Z"
  }
}

Update User

PATCH /Users/{id}

curl -X PATCH https://api.truthvouch.com/scim/v2/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://api.truthvouch.com/scim/v2/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://api.truthvouch.com/scim/v2/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": "john.doe@company.com",
  "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://api.truthvouch.com/scim/v2/Groups \
  -H "Authorization: Bearer scim_token_here"

Create Group

POST /Groups

curl -X POST https://api.truthvouch.com/scim/v2/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": "john.doe@company.com"
      }
    ]
  }'

---

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://api.truthvouch.com/scim/v2
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 →