SCIM

QA Sphere supports SCIM 2.0 (System for Cross-domain Identity Management) so identity providers like Okta, Microsoft Entra ID, and Authentik can automatically provision, update, and deactivate user accounts. Instead of managing users manually in QA Sphere, your IdP keeps them in sync — a new hire is created when assigned, attribute changes are pushed automatically, and a departing employee is deactivated when their access is removed.

Base URL

https://{your-company}.{your-region-code}.qasphere.com/api/scim/v2

Authentication

SCIM uses the same API keys as the rest of QA Sphere. Generate one in Settings → API Keys under an account with the Admin role. See the API authentication guide for details on creating keys.

Configure your identity provider with one of the following Authorization header formats — most IdPs default to Bearer:

Authorization: Bearer {your-api-key}
Authorization: Basic {base64("ApiKey:" + your-api-key)}

caution

SCIM requests act on your tenant's user directory. Store the API key in your IdP's secret manager and rotate it like any other production credential.

Configuring Your Identity Provider

In your IdP's SCIM application, set:

Field	Value
SCIM endpoint	https://{your-company}.{your-region-code}.qasphere.com/api/scim/v2
Auth scheme	Bearer token (or HTTP Basic, depending on the connector)
Token	Your QA Sphere API key

Once connected, the IdP can:

• Create users by assigning the QA Sphere app to a user or group
• Update users when their name or email changes upstream
• Deactivate users by unassigning them or disabling them in the IdP
• Reactivate users by re-enabling them

How User Lifecycle Works

Provisioning

When the IdP creates a user, QA Sphere creates an account with the provided name and email. Passwords are never set via SCIM — the new user sets their initial password through the Forgot password flow on the sign-in page.

New users are created with the User role and granted access to all projects in the workspace. Role and project access changes are not driven by SCIM — adjust them directly in QA Sphere under Settings → Users.

Updating

The IdP can update the user's name, email, externalId, and the active flag. Email changes update the user's login email and end any active sessions; the user signs back in with the new address.

Deactivation and Reactivation

Setting active: false suspends the user. Their account is preserved along with all historical test cases, runs, results, and audit history they authored — they simply cannot sign in. Setting active: true restores access.

QA Sphere does not support hard-deleting users via SCIM. This is intentional: removing a user would orphan the QA history they contributed.

Supported Attributes

QA Sphere maps a focused subset of the SCIM User schema. Because QA Sphere stores a single name and a single email per user, several SCIM attributes collapse onto the same field:

SCIM attribute	QA Sphere field
userName	Email (also used to sign in)
emails[] — entry marked primary: true, or the first non-empty entry	Email
displayName (falls back to name.formatted, then name.givenName + name.familyName)	Name
active	Account enabled
externalId	IdP correlation ID

Other attributes in the request payload are accepted but ignored.

Constraints

A few rules are enforced to keep the directory consistent with QA Sphere's user model:

• userName must be a valid email address. QA Sphere has no separate username — the email is the identifier used to sign in.
• userName must match the primary email. If emails is included in the payload, its primary value must equal userName; otherwise the request is rejected with 400 Bad Request.
• Email must be unique across the workspace. Conflicts return 409 Conflict.
• Workspace owners cannot be modified by non-owner callers, and an owner cannot be deactivated through SCIM. Transfer ownership in QA Sphere first if you need to deprovision an owner.
• You cannot deactivate the user whose API key is being used. Use a different admin's key, or have another admin perform the change.

Auditing

Every SCIM-driven change is recorded in the QA Sphere audit log under Settings → Audit Log, including user creation, attribute updates, deactivation, and reactivation. Filter by the SCIM-specific event types to review IdP activity.

Troubleshooting

Symptom	Likely cause
401 Unauthorized	API key missing, malformed, or revoked. Re-issue from Settings → API Keys.
403 Forbidden	The API key's owner is not an Admin, or you're trying to modify a workspace owner.
400 "userName must be an email address"	Configure your IdP to send the user's email as userName.
400 "primary email must match userName"	Map the same value to both userName and the email entry in your IdP attribute mapping.
409 Conflict	A user with that userName already exists in QA Sphere.

If you need help, contact QA Sphere support and include the SCIM request and response (with secrets redacted).