Topaz SCIM Attribute Reference

Overview

Use this reference when mapping attributes from your identity provider to Topaz SCIM.

Topaz Extension URN

Use this SCIM extension URN for Topaz-specific attributes:

urn:ietf:params:scim:schemas:extension:topaz:2.0:User

Standard SCIM Fields

Topaz supports these standard SCIM user fields:

userName
Recommended use: the user's email address or login identifier

active
Recommended use: user lifecycle state
Note: false is treated as a deprovision action

displayName
Recommended use: the user's display name

name.givenName
Recommended use: the user's first name

name.familyName
Recommended use: the user's last name

emails[].value
Required use: the user's primary email address

emails[].primary
Recommended use: identify the primary email value

externalId
Optional use: your identity provider's unique identifier for the user

Topaz Extension Fields

tenantKey
Type: string
Use: identifies the Topaz tenant
Example: tk_sample-tenant
Note: if sent, it must match the tenant associated with the bearer token

controllerKey
Type: string
Use: identifies the Topaz controller or team
Example: ck_photo-team
Note: required for provisioning writes

managedSeatEnabled
Type: boolean
Use: enables or disables managed-seat provisioning
Recommended value: true

managedSeatRole
Type: string
Allowed values: sub_user, sub_admin
Use: sets the Topaz managed-seat role
Recommended default: sub_user

managedSeatCount
Type: integer
Use: sets the managed-seat count
Recommended default: 1

productScope
Type: string
Allowed values: enterprise_default, selected_products
Use: aligns provisioning with the configured Topaz product scope
Recommended default: enterprise_default

ssoRuleAction
Type: string
Allowed values: bypass_sso, require_sso
Use: optional SSO rule behavior for the provisioned user

Azure Entra Mapping Guidance

For Azure Entra, treat these as app-level constants:

- tenantKey
- controllerKey
- productScope

In the simplest Azure Entra setup, these may also be constants:

- managedSeatEnabled
- managedSeatRole
- managedSeatCount
- ssoRuleAction

This gives you a working baseline, but it means those values are shared across users in that provisioning app.

If you need true per-user control from Azure, those fields must come from user-specific Azure attributes rather than constants.

Recommended Default Mapping

For a standard enterprise managed-seat deployment, Topaz recommends:

- tenantKey: the tenantKey provided by Topaz
- controllerKey: the controllerKey provided by Topaz
- managedSeatEnabled: true
- managedSeatRole: sub_user
- managedSeatCount: 1
- productScope: enterprise_default

Provisioning and Deprovisioning

Topaz treats both of the following as deprovision actions:

- active=false
- DELETE /Users/{id}

This removes SCIM-managed assignments and marks the user inactive in tenant state.

Topaz currently supports exact-match SCIM filters using eq for:

- userName
- emails.value
- externalId
- id

Examples:

userName eq "user@example.com"
emails.value eq "user@example.com"
externalId eq "entra-object-id"
id eq "123"

PATCH Support

Topaz supports SCIM PATCH with add, replace, and remove operations for supported fields.

Common PATCH paths include:

- active
- userName
- displayName
- externalId
- name.givenName
- name.familyName
- emails
- emails.value
- urn:ietf:params:scim:schemas:extension:topaz:2.0:User:tenantKey
- urn:ietf:params:scim:schemas:extension:topaz:2.0:User:controllerKey
- urn:ietf:params:scim:schemas:extension:topaz:2.0:User:managedSeatEnabled
- urn:ietf:params:scim:schemas:extension:topaz:2.0:User:managedSeatRole
- urn:ietf:params:scim:schemas:extension:topaz:2.0:User:managedSeatCount
- urn:ietf:params:scim:schemas:extension:topaz:2.0:User:productScope
- urn:ietf:params:scim:schemas:extension:topaz:2.0:User:ssoRuleAction

Azure Entra compatibility note:

Azure Entra may send Topaz extension fields as bare PATCH paths such as:

- tenantKey
- controllerKey
- managedSeatEnabled
- managedSeatRole
- managedSeatCount
- productScope
- ssoRuleAction

Topaz SCIM accepts both the namespaced Topaz extension paths and those Azure-style bare paths.

Example PATCH Payload

{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "Replace",
"path": "urn:ietf:params:scim:schemas:extension:topaz:2.0:User:managedSeatCount",
"value": 2
},
{
"op": "Replace",
"path": "urn:ietf:params:scim:schemas:extension:topaz:2.0:User:managedSeatRole",
"value": "sub_admin"
}
]
}

Example Deprovision via PATCH

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

Limits

Topaz does not currently support:

- SCIM Groups (coming soon)
- SCIM bulk operations

Configure Identity Providers

Quick Start (Legacy)