SCIM Provisioning

Hawcx implements the SCIM 2.0 protocol so your service provider directory can create, update, and deactivate user accounts in Hawcx automatically. Instead of managing users in Hawcx by hand, your SP pushes changes as soon as they happen in your directory of record.

This page covers the protocol surface: endpoints, authentication, attributes, and provisioning semantics. For SP-specific setup, see the Microsoft Entra guide.

Endpoints

All SCIM endpoints are scoped to your tenant and served from sandbox.hawcx.com.

Method	Endpoint	Purpose
`GET`	`/v1/scim/{project_id}/ServiceProviderConfig`	Capability discovery
`GET`	`/v1/scim/{project_id}/Users`	List or filter users
`GET`	`/v1/scim/{project_id}/Users/{user_id}`	Fetch one user
`POST`	`/v1/scim/{project_id}/Users`	Create user (201)
`PATCH`	`/v1/scim/{project_id}/Users/{user_id}`	Update user attributes
`DELETE`	`/v1/scim/{project_id}/Users/{user_id}`	Delete user (204)

Requests and responses use Content-Type: application/scim+json.

Authentication

SCIM requests authenticate with a per-tenant bearer token:

Authorization: Bearer <your-scim-token>

The token is issued by Hawcx support alongside your SAML credentials. If SCIM is not enabled on the tenant the API returns 404; if the token is missing or wrong it returns 401.

User Attributes

The create and patch endpoints accept the SCIM 2.0 core User schema. Hawcx reads these fields:

SCIM attribute	Notes
`userName`	Required, non-blank. Hawcx uses this as the primary login identifier
`externalId`	Recommended. Stable identifier from your SP directory
`name.givenName`	Optional
`name.familyName`	Optional
`displayName`	Optional
`emails[].value`	Use `type: "work"` and `primary: true` for the main email
`phoneNumbers[].value`	E.164 format expected (e.g. `+14155551234`)
`active`	`true` to enable, `false` to deactivate

Other SCIM attributes (e.g. addresses, roles, enterprise:user extension) are ignored.

Filtering

The GET /Users endpoint supports the standard SCIM filter expression. The most common form is exact-match lookup by userName:

GET /v1/scim/{project_id}/Users?filter=userName+eq+%[email protected]%22

Pagination is via startIndex (1-based) and count (max 100 per page). An invalid filter returns 400 with scimType: "invalidFilter".

Provisioning Behavior

When a user is created via SCIM, Hawcx marks the user as SCIM-provisioned. This provenance has two effects:

Phone is locked. While the user is SCIM-provisioned and the tenant policy treats SCIM attributes as authoritative, the user cannot change their own phone number through the auth flow. Attempts to re-enroll SMS or run a change_phone_number step-up return PHONE_LOCKED_BY_PROVISIONING. To change the phone, update it via SCIM PATCH from your SP.
Single source of truth. Updates pushed via SCIM PATCH overwrite the corresponding fields in Hawcx. Local edits to those fields can be overwritten on the next sync.

Email and display name are not locked

Only phone is enforced as SCIM-authoritative on the current build. Users can still update email and display name via the standard auth flow.

Errors

Hawcx returns standard SCIM error responses on the application/scim+json content type.

Status	`scimType`	When
`400`	`invalidValue`	Required field missing or malformed
`400`	`invalidFilter`	Filter expression could not be parsed
`401`	—	Missing or wrong bearer token
`404`	—	User not found, or SCIM not enabled on the tenant
`409`	`uniqueness`	`userName`, email, or phone already in use
`503`	—	SCIM token not configured or tenant service unavailable

Quick Test

Once you have your project ID and SCIM token, you can smoke-test the endpoint from the command line:

# Discovery — should return ServiceProviderConfig JSON
curl -s -w "\nHTTP %{http_code}\n" \
  "https://sandbox.hawcx.com/v1/scim/{project_id}/ServiceProviderConfig" \
  -H "Authorization: Bearer <your-scim-token>" \
  -H "Accept: application/scim+json"

# List users (should return SCIM ListResponse)
curl -s "https://sandbox.hawcx.com/v1/scim/{project_id}/Users?count=10" \
  -H "Authorization: Bearer <your-scim-token>" \
  -H "Accept: application/scim+json"

Provider Guides

Microsoft Entra ID (Azure AD) — covers both SAML federation and SCIM provisioning in one walkthrough

SCIM Provisioning

On this page