HappySignals SCIM API Reference

The API implements SCIM 2.0 as defined in RFC 7643 and RFC 7644.

Base URL

https://<tenant>.<environment>.happysignals.com/scim/v2/

Environments include e.g. emea, us, uk. Your exact base URL is confirmed by HappySignals support during onboarding.

Authentication

The API uses the OAuth 2.0 client credentials grant (RFC 6749 §4.4). Microsoft Entra ID handles this exchange transparently when configured via the gallery integration; this section documents the underlying flow for programmatic callers.

Token endpoint

POST https://<tenant>.<environment>.happysignals.com/oauth/token/ Content-Type: application/x-www-form-urlencoded

Request parameters:

Successful response (HTTP 200):

{   "access_token": "<JWT>",   "token_type": "Bearer",   "expires_in": 900 }

The access_token is a JWT signed with HS256. It carries the standard claims iss, sub, aud, iat, exp, jti, and client_id. iss and aud both resolve to your tenant's primary domain.

Access tokens expire after 15 minutes. No refresh tokens are issued — obtain a new access token by re-running the client credentials exchange.

Using the access token

Send the access token as a bearer token on every SCIM request:

Authorization: Bearer <access_token>

Token endpoint errors

Supported user attributes

SCIM User resources use the core schema plus three extensions. Send the extension URNs in the schemas array alongside the core User schema when writing extension attributes.

Discovery endpoints (/Schemas, /ResourceTypes, /ServiceProviderConfig) return the authoritative machine-readable schema.

Endpoints

All endpoints are relative to the base URL.

Discovery

Users

Filtering and pagination

GET /Users accepts filter, startIndex, and count.

Filter grammar. Only the eq operator on userName or externalId is supported:

GET /Users?filter=userName eq "alice@acme.com" GET /Users?filter=externalId eq "aaaabbbb-0000-cccc-1111-dddd2222eeee"

Any other operator, attribute, or combination returns 400 invalidFilter.

Pagination.

• startIndex is 1-based. Defaults to 1.
• count defaults to 100 and is capped at 100.
• Sort order is stable but not client-controllable. No sortBy / sortOrder parameters are supported.

Responses follow the SCIM ListResponse shape:

{   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],   "totalResults": 42,   "startIndex": 1,   "itemsPerPage": 20,   "Resources": [ ... ] }

Behaviour notes

DELETE is destructive.
DELETE /Users/{id} permanently removes the identity from HappySignals. For reversible deprovisioning (the pattern Microsoft Entra ID and most IdPs use), send PATCH with active set to false instead.

PATCH is lenient.
Unrecognised operations, paths, or attributes are silently skipped. The request only fails with 400 if no operation could be applied.

PATCH filter paths are not supported.
Expressions like emails[type eq "work"].value in a PATCH path return 400 invalidPath. Send the enclosing attribute as an object instead.

Not supported: /Groups, /Bulk, /Me, sort, ETag (If-Match), password change (changePassword).

Errors

All errors use the standard SCIM error envelope:

{   "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],   "status": "400",   "detail": "Human-readable description",   "scimType": "invalidValue" }

scimType values

OAuth-layer errors reaching SCIM endpoints

If the bearer token fails validation, the SCIM endpoint returns HTTP 401 with one of the following detail strings:

• Token has expired. — request a new access token.
• Invalid token audience. / Invalid token issuer. — the token was issued for a different HappySignals tenant.
• Client not found. — the OAuth client has been deactivated. Contact support.

End-to-end example

Provision, retrieve, update, and deactivate a user against the tenant acme.emea.happysignals.com.

1. Obtain an access token

curl -X POST https://acme.emea.happysignals.com/oauth/token/ \   -H "Content-Type: application/x-www-form-urlencoded" \   -d "grant_type=client_credentials" \   -d "client_id=cli_abc123" \   -d "client_secret=sec_xxxxxxxx"

Response:

{   "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",   "token_type": "Bearer",   "expires_in": 900 }

2. Create a user

curl -X POST https://acme.emea.happysignals.com/scim/v2/Users \   -H "Authorization: Bearer eyJhbGciOi..." \   -H "Content-Type: application/scim+json" \   -d '{     "schemas": [       "urn:ietf:params:scim:schemas:core:2.0:User",       "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"     ],     "userName": "alice@acme.com",     "externalId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",     "active": true,     "name": {       "givenName": "Alice",       "familyName": "Example"     },     "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {       "department": "Engineering",       "organization": "Acme Corp"     }   }'

Response (HTTP 201) includes the assigned id, e.g. "id": "1234".

3. Retrieve the user

curl https://acme.emea.happysignals.com/scim/v2/Users/1234 \   -H "Authorization: Bearer eyJhbGciOi..."

4. Deactivate the user

curl -X PATCH https://acme.emea.happysignals.com/scim/v2/Users/1234 \   -H "Authorization: Bearer eyJhbGciOi..." \   -H "Content-Type: application/scim+json" \   -d '{     "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],     "Operations": [       { "op": "replace", "path": "active", "value": false }     ]   }'

Response: HTTP 200 with the updated resource. The user is retained in HappySignals but marked inactive. To permanently delete instead, use DELETE /Users/1234.