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

  1. 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/v2

    Use the second URL if your account has an account-specific API domain. Replace the base URL in the examples below if yours differs.

  2. 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:secret string for either header. Use Bearer for clients such as Microsoft Entra ID that only offer a bearer token field. Alloy rejects OAuth access tokens from POST /oauth/bearer with 401 (unauthorized). /ServiceProviderConfig lists only HTTP Basic as its authentication scheme.

  3. Set the environment variables ALLOY_API_TOKEN and ALLOY_API_SECRET to your API token and secret before running the curl examples. Keep their values out of source control and shared logs. The examples use -u for 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):

MethodPathReturns
GET/ResourceTypesAll 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 IDEndpointSchema URNDescription
User/Usersurn:ietf:params:scim:schemas:core:2.0:UserAlloy dashboard user
Group/Groupsurn:ietf:params:scim:schemas:core:2.0:GroupGroup that Alloy represents through a role
Role/Rolesurn:usealloy:params:scim:schemas:core:2.0:RoleRead-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.

MethodPathReturns
GET/SchemasList 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"
    }
  ]
}
SchemaDeclared attributes
UseruserName, name (givenName, familyName), displayName, emails (value, type, primary), phoneNumbers (value, type), active, groups (value, display), roles (value, display, primary), entitlements (value, display, type)
GroupdisplayName, members (value, $ref, display)
RoledisplayName, 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

  • /ResourceTypes and /Schemas always return the complete list. Alloy ignores startIndex and count.
  • A filter parameter on /ResourceTypes, /ResourceTypes/{resourceTypeId}, /Schemas, or /Schemas/{schemaId} returns 403. /ServiceProviderConfig ignores 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.

StatusCauseAction
401Missing or invalid credentialsSend your account's API token and secret using Basic or the Base64-encoded Bearer format described above
403Unsupported filter parameterRemove filter from the discovery request
404Unknown resource type or schema URNUse User, Group, or Role for resource types; use the complete URN from the resource table for schemas

Did this page help you?