SCIM Discovery
Inspect Alloy SCIM 2.0 discovery endpoints, authentication, service provider capabilities, resource types, schemas, and discovery errors.
Use Alloy's SCIM 2.0 discovery endpoints to inspect supported features, resource types, and attribute schemas.
SCIM (System for Cross-domain Identity Management) supports user provisioning (creating and managing user accounts) across applications. Discovery endpoints describe the features and account data your integration can work with. A schema defines the fields, called attributes, for each resource type, such as a user or group.
For provisioning setup, see SCIM with Okta or SCIM with Azure.
Base URL and authentication
-
Choose your SCIM base URL. Use your Production API base URL with
/scim/v2:https://api.alloy.co/scim/v2 https://{{account_slug}}.api.alloy.com/scim/v2Use the second URL if your account has an account-specific API domain. Replace the base URL in the examples below if yours differs.
-
Obtain your Alloy API token and secret from Account-Level API Keys. Every discovery endpoint requires authentication using either header:
Authorization: Basic <base64(token:secret)> Authorization: Bearer <base64(token:secret)>Join your API token and secret with a colon, then Base64-encode the resulting
token:secretstring for either header. Use Bearer for clients such as Microsoft Entra ID that only offer a bearer token field. Alloy rejects OAuth access tokens fromPOST /oauth/bearerwith401(unauthorized)./ServiceProviderConfiglists only HTTP Basic as its authentication scheme. -
Set the environment variables
ALLOY_API_TOKENandALLOY_API_SECRETto your API token and secret before running the curl examples. Keep their values out of source control and shared logs. The examples use-ufor HTTP Basic authentication.
Discovery responses use Content-Type: application/scim+json and differ between customers only in the absolute URLs in meta.location.
Service provider configuration
Call GET /ServiceProviderConfig to inspect advertised capabilities and verify authentication:
curl -u "$ALLOY_API_TOKEN:$ALLOY_API_SECRET" \
"https://api.alloy.co/scim/v2/ServiceProviderConfig"Check for the service provider configuration schema and httpbasic authentication scheme in the response. The example reports support for filtering and sorting, with filter.maxResults set to 100:
Example service provider configuration response
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
"patch": { "supported": false },
"bulk": { "supported": false, "maxOperations": 0, "maxPayloadSize": 0 },
"filter": { "supported": true, "maxResults": 100 },
"changePassword": { "supported": false },
"sort": { "supported": true },
"etag": { "supported": false },
"authenticationSchemes": [
{
"type": "httpbasic",
"name": "HTTP Basic",
"description": "Alloy API token and secret, sent as HTTP Basic credentials",
"specUri": "https://www.rfc-editor.org/info/rfc7617",
"primary": true
}
],
"meta": {
"resourceType": "ServiceProviderConfig",
"location": "https://api.alloy.co/scim/v2/ServiceProviderConfig"
}
}filter and sort describe support on /Users and /Groups, rather than on discovery endpoints. Alloy marks PATCH as unsupported because its implementation does not meet all requirements of RFC 7644 (the SCIM protocol specification). These capability flags do not describe how requests to create, update, or delete resources behave.
For a 401 response, check that both environment variables contain your account's API token and secret, rather than an OAuth access token.
Resource types
Use these endpoints to find the paths for each resource type and its schema URN (uniform resource name, an identifier for the schema):
| Method | Path | Returns |
|---|---|---|
GET | /ResourceTypes | All three resource types in a SCIM list response with totalResults, startIndex, itemsPerPage, and Resources |
GET | /ResourceTypes/{resourceTypeId} | One resource type; use User, Group, or Role. Alloy ignores letter case when matching the ID |
| Resource type ID | Endpoint | Schema URN | Description |
|---|---|---|---|
User | /Users | urn:ietf:params:scim:schemas:core:2.0:User | Alloy dashboard user |
Group | /Groups | urn:ietf:params:scim:schemas:core:2.0:Group | Group that Alloy represents through a role |
Role | /Roles | urn:usealloy:params:scim:schemas:core:2.0:Role | Read-only catalog of roles and their permissions |
The Role resource and its schema URN are specific to Alloy. Each entry describes a role and the entitlements (permissions) it grants. Every resource type reports an empty schemaExtensions list.
curl -u "$ALLOY_API_TOKEN:$ALLOY_API_SECRET" \
"https://api.alloy.co/scim/v2/ResourceTypes/Role"The response identifies the Role resource type, its /Roles endpoint, and its Alloy-specific schema URN. The schemaExtensions list is empty:
Example Role resource type response (abbreviated)
{
"id": "Role",
"endpoint": "/Roles",
"schema": "urn:usealloy:params:scim:schemas:core:2.0:Role",
"schemaExtensions": []
}Schemas
Use these endpoints to inspect the fields each schema declares. RFC 7643 (the SCIM schema specification) defines characteristics such as type, mutability, and uniqueness. Type describes the kind of value, and mutability specifies whether you can change it. Uniqueness specifies where values must be unique.
| Method | Path | Returns |
|---|---|---|
GET | /Schemas | List of the User, Group, and Role schemas |
GET | /Schemas/{schemaId} | One schema; use its complete schema URN. Alloy ignores letter case when matching the URN |
Keep colons in schema URNs as written, or encode them as %3A in the URL path. /Schemas/{schemaId} expects a URN rather than a resource type ID, so /Schemas/User returns 404.
curl -u "$ALLOY_API_TOKEN:$ALLOY_API_SECRET" \
"https://api.alloy.co/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"The response identifies the User schema and describes its attributes. In this abbreviated example, Alloy requires a string for userName, and you cannot change its value (mutability: immutable):
Example User schema response (abbreviated)
{
"id": "urn:ietf:params:scim:schemas:core:2.0:User",
"attributes": [
{
"name": "userName",
"type": "string",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "immutable",
"returned": "default",
"uniqueness": "server"
}
]
}| Schema | Declared attributes |
|---|---|
| User | userName, name (givenName, familyName), displayName, emails (value, type, primary), phoneNumbers (value, type), active, groups (value, display), roles (value, display, primary), entitlements (value, display, type) |
| Group | displayName, members (value, $ref, display) |
| Role | displayName, description, entitlements (value, display, type) |
Schemas omit the common resource attributes schemas, id, externalId, and meta. They also exclude attributes Alloy accepts but discards, such as title, locale, and addresses.
Discovery limits and errors
/ResourceTypesand/Schemasalways return the complete list. Alloy ignoresstartIndexandcount.- A
filterparameter on/ResourceTypes,/ResourceTypes/{resourceTypeId},/Schemas, or/Schemas/{schemaId}returns403./ServiceProviderConfigignores it. - Unknown resource types or schema URNs return
404.
Discovery authentication errors use the SCIM error schema (urn:ietf:params:scim:api:messages:2.0:Error) and Content-Type: application/scim+json.
| Status | Cause | Action |
|---|---|---|
401 | Missing or invalid credentials | Send your account's API token and secret using Basic or the Base64-encoded Bearer format described above |
403 | Unsupported filter parameter | Remove filter from the discovery request |
404 | Unknown resource type or schema URN | Use User, Group, or Role for resource types; use the complete URN from the resource table for schemas |
Updated 4 days ago