Skip to content
HamstikHamstik Docs

SCIM user provisioning

Hamstik supports Organization-scoped SCIM 2.0 user provisioning. Your identity provider (IdP) can create pending member invitations, keep names and emails up to date, and deactivate members when they leave — with Hamstik keeping the final say over who actually gets access.

This page covers the supported SCIM subset, the credential lifecycle, how provisioned people get access, and the limits of the integration. Protocol references: RFC 7643 (schema) and RFC 7644 (protocol).

Availability

SCIM provisioning requires Enterprise coverage for the Organization. When coverage lapses:

  • the active connection keeps working, so members are not silently dropped;
  • creating, rotating, or converting requires restoring coverage; and
  • revoking the connection is always available to Organization admins and owners.

Connect your identity provider

  1. In Hamstik, open Organization Settings → User provisioning and create the connection. You confirm your password, and the SCIM bearer token is shown exactly once — store it in your IdP immediately; it cannot be read back.

  2. Point your IdP at the Hamstik SCIM endpoint:

    Base URL: https://hamstik.com/api/scim/v2
    Auth:     Bearer token (the credential from step 1)

    The credential is bound to one Organization: it can never call the general Hamstik API or another Organization’s provisioning service, and a token from another Organization sees the same 404 for a resource as a missing one.

  3. Rotate the token whenever your IdP configuration changes hands or a secret may have been exposed; the previous token stops working immediately. Revoking the connection is terminal and always available.

Provisioning tokens are separate from Personal Access Tokens. A hstk_scim_… token is rejected everywhere PATs are used, and PATs are rejected on the SCIM endpoint.

What your identity provider can do

Hamstik implements the standard SCIM discovery documents and the User resource, with the supported subset declared in GET /ServiceProviderConfig, GET /ResourceTypes, and GET /Schemas:

Capability Support
ServiceProviderConfig, ResourceTypes, Schemas Yes (no credential required)
GET /Users with pagination Yes — startIndex and count, default 50, maximum 100
GET /Users with filters Yes — userName eq "…" and externalId eq "…" only
POST /Users Yes — create or reconcile by externalId
PUT /Users/{id} Yes — full replace; externalId cannot change
PATCH /Users/{id} Yes — replace/add/remove on userName, active, name.*, emails
DELETE /Users/{id} Yes — deactivates and removes the managed membership
Bulk, Groups, Teams, Enterprise extension Not supported — requests fail explicitly
Password provisioning Not supported — Hamstik never sets or resets passwords via SCIM
Sorting (sortBy/sortOrder) Not supported
Custom filters (co, sw, pr, …) Not supported — rejected with invalidFilter

Requests and responses use application/scim+json. Errors use the RFC 7644 error form with scimType where applicable (invalidFilter, invalidPath, invalidValue, uniqueness, notFound).

User attributes

Create, replace, and patch accept:

  • userName — required; trimmed and case-normalized, unique within the connection;
  • externalId — required; your IdP’s stable identifier, unique within the connection, and immutable once created (an authorized migration is a separate, explicit operation);
  • name — givenName, familyName, and formatted are kept;
  • emails — exactly one primary email; trimmed and case-normalized, unique within the connection; conflicting updates fail atomically;
  • active — the requested state (see below).

Provisioned identities expose a documented read-only status extension, urn:hamstik:params:scim:schemas:extension:hamstik:2.0:ProvisioningStatus, whose status attribute reports pending, active, or deactivated, plus the invitation expiry and last failure summary where applicable.

How a provisioned person gets access

Provisioning never grants access by itself:

  1. Pending invitation. A new external identity becomes a pending identity: an invitation for a non-privileged member role. Hamstik emails the provider address, but the invitation is never linked to an account by email matching, and no password is created.
  2. Authenticated acceptance. The person signs in to Hamstik — with an existing account, or a new one they create — and opens the invitation link (https://hamstik.com/scim/accept/<token>). Accepting binds that specific identity to the account they are signed in with. The invitation is single-use and expires after seven days; re-provisioning a still-pending identity re-issues it.
  3. Membership. On acceptance, a regular member membership is created (subject to seat availability). SCIM never grants owner or admin roles, Project grants, or Team memberships, and reactivation never restores previously held privileges.

Until acceptance, a pending identity holds no effective membership authority. Existing Hamstik accounts that were invited must actively accept; their memberships are never auto-created by email match.

Deactivation and reactivation

  • PATCH with active: false (or DELETE) removes the Organization membership this connection manages through the same member-lifecycle service the UI uses. Sessions, PATs, and jobs lose authority in that Organization immediately. History is preserved, and memberships in other Organizations are untouched.
  • Members who were added directly in Hamstik (or converted — see below) are not silently deactivated: SCIM manages only the memberships it created or that were explicitly converted.
  • The last Organization owner is protected: deactivation of an owner-managed identity returns an actionable conflict instead of bypassing the safeguard.
  • Reactivating (active: true) re-creates a member-role membership after the eligibility and seat checks. Prior roles, Project grants, and Team memberships are never restored automatically.

Converting an existing member

Organization admins and owners can explicitly place an existing direct member under SCIM management from the same settings section (Convert existing member). The member keeps their role, history, and Project grants; only the management source changes, and the conversion is audited.

Administration and auditing

The User provisioning settings section shows:

  • connection status, creation/rotation times, and the last request seen;
  • managed, pending, and error identity counts and the last synchronization failures (per identity and per connection);
  • the provisioned identity list with each person’s acceptance state — token values are never displayed after creation.

Provisioning operations are recorded in an append-only audit: source and external ID, operation and outcome, and any membership change. Credential management (create, rotate, revoke, convert) is attributed to the acting administrator.

Error behavior you can rely on

  • Duplicate or conflicting identifiers fail with a generic uniqueness conflict that never reveals whether an email belongs to another account or Organization.
  • Failed operations leave no partial membership behind.
  • Retried provisioning (the same externalId again) reconciles in place instead of creating duplicates, and a revoked or expired credential can never provision.
  • Suspended Organizations stop provisioning along with every other write.