1. Docs
  2. API Reference
  3. Provision a user

Provision a user

POST/scim/v2/directories/{directoryId}/Users

SCIM 2.0 (RFC 7644 §3.3). Provisions a person the identity provider pushes into this directory, creating the identity or linking the existing one with the same address, and grants access to the directory's Environment (and organization, for an organization's directory). Returns the SCIM User resource with 201. Errors use SCIM's error schema (RFC 7644 §3.12).

Path Parameters

directoryIdstring Required

The directory the SCIM token was minted for.

Request body

application/json

schemasstring[] Optional
userNamestring Optional

The sign-in email. When absent, the primary email (or the first) is used.

externalIdstring Optional

The provider's own id for the person

nameScimNameDto Optional
emailsScimEmailDto[] Optional
activeboolean Optional

`false` deprovisions; an absent value leaves it unchanged

Responses

application/scim+json

  • schemasstring[]*
  • idstring*

    This directory's id for the person

  • externalIdstring
  • userNamestring*

    The sign-in email, lowercased

  • nameScimNameDto*
  • emailsScimEmailDto[]*
  • activeboolean*

    Whether the person is active in this directory

  • metaScimMetaDto*

application/scim+json

  • schemasstring[]*
  • statusstring*

    The HTTP status, as a string

  • detailstring*
  • scimTypestring

    Present for some refusals, e.g. `uniqueness`

application/scim+json

  • schemasstring[]*
  • statusstring*

    The HTTP status, as a string

  • detailstring*
  • scimTypestring

    Present for some refusals, e.g. `uniqueness`

application/scim+json

  • schemasstring[]*
  • statusstring*

    The HTTP status, as a string

  • detailstring*
  • scimTypestring

    Present for some refusals, e.g. `uniqueness`

Returned object

ScimUserDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/scim/v2/directories/value/Users" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "string",
    "externalId": "string",
    "name": {
      "givenName": "string",
      "familyName": "string"
    },
    "emails": [
      {
        "value": "string",
        "primary": false,
        "type": "work"
      }
    ],
    "active": false
  }'
Response
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "string",
  "externalId": "string",
  "userName": "string",
  "name": {
    "givenName": "string",
    "familyName": "string"
  },
  "emails": [
    {
      "value": "string",
      "primary": false,
      "type": "work"
    }
  ],
  "active": false,
  "meta": {
    "resourceType": "User",
    "created": "2026-04-20T12:00:00.000Z",
    "lastModified": "2026-04-20T12:00:00.000Z",
    "location": "string",
    "version": "string"
  }
}
 Related endpoints Was this page helpful?

Tell us how we can improve this guide.

Canopy