Generic SCIM Endpoint - Create User

Last modified on March 24, 2023

The Create User endpoint creates the requested user in StrongDM.

Request

Endpoint

/provisioning/generic/v2/Users

HTTP method

POST

Request body attributes

AttributeRequirementDescriptionExample
activeRequiredUser’s status (Boolean); set to false to suspend a user upon creationactive: false
displayNameOptionalName of the user that is suitable for display to end users"Bob Belcher"
emails.displayOptionalEmail addresses for the user with subattribute display (canonicalized representation of user’s email value)"[{"display": "primary email"}]
emails.primaryOptionalEmail addresses for the user with subattribute primary (Boolean)"emails": [{"name": {"primary": true}]
emails.typeOptionalEmail addresses for the user with subattribute type (human-readable classification of user’s email)"emails": [{"name": {"type": "work"}]
emails.valueOptionalEmail addresses for the user with subattribute value (user’s email value)"emails": [{"name": {"value": "bob.belcher@strongdm.com"}]
entitlementsOptionalList of entitlements for the user that represent a thing the user has; may include subattributes value, display, primary (Boolean), and type[{"value": "value", "display": "display", "primary": true, "type": "one"}]
externalIdOptionalIdentifier (string) for the resource as defined by the provisioning client"701984"
localeOptionalUser’s default location for purposes of localizing items such as currency, date time format, or numerical representations"en-US"
name.familyNameRequiredUser’s name with subattribute familyName (last name)"name": {"familyName": "Belcher"}
name.formattedOptionalUser’s name with subattribute formatted (full name, including all middle names, titles, and suffixes as appropriate, formatted for display)"name": {"formatted": "Mr. Bob Belcher, III"}
name.givenNameRequiredUser’s name with subattribute givenName (first name)"name": {"givenName": "Bob"}
name.honorificPrefixOptionalUser’s name with subattribute honorificPrefix (title)"name": {"honorificPrefix": "Mr."}
name.honorificSuffixOptionalUser’s name with subattribute honorificSuffix (suffix)"name": {"honorificSuffix": "III"}
name.middleNameOptionalUser’s name with subattribute middleName (middle name)"name": {"middleName": "Jay"}
nickNameOptionalCasual way to address the user in real life"Bobby"
preferredLanguageOptionalUser’s preferred written or spoken language(s)"en-US"
profileUrlOptionalURI that is a uniform resource locator and that points to a location representing the user’s online profile"https://login.example.com/bobbelcher"
rolesOptionalList of roles for the user that collectively represent who the user is; does not correspond to StrongDM’s internal role entity type; only groups in SCIM correspond to StrongDM roles[{"value": "value", "display": "display", "primary": true, "type": "one"}]
schemasRequiredSchema URI for representing users; include the value as indicated in the example["urn:ietf:params:scim:schemas:core:2.0:User"]
timezoneOptionalUser’s time zone, in IANA Time Zone database format"America/Los_Angeles"
titleOptionalUser’s title"Vice President"
userNameRequiredUser’s username"myUser@example.test"
x509CertificatesOptionalList of certificates associated with the resource[{"value":"aGVsbG8gd29ybGQK"}]

Enterprise User extension attributes

The following attributes are supported underneath the Enterprise User Schema extension.

In order to identify the enterprise User extension, these attributes are prefixed with the schema URI urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:.

AttributeRequirementDescriptionExample
costCenterOptionalIdentifies the name of a cost center"4130"
departmentOptionalIdentifies the name of a department"Operations"
divisionOptionalIdentifies the name of a division"Research and Development"
employeeNumberOptionalString identifier assigned to a person, typically based on order of hire or association with an organization"701984"
managerOptionalUser’s manager; may include subattributes value (identifier of the SCIM resource representing the user’s manager), $ref (URI of the SCIM resource representing the user’s manager), and displayName (display name of the user’s manager; optional){"value": "26118915-6090-4610-87e4-49d8ca9f808d", "$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d", "displayName": "Alice Glick"}
organizationOptionalIdentifies the name of an organization"Universe"

Example request with all supported attributes

The following Create User example request includes all supported attributes.

POST app.strongdm.com/provisioning/generic/v2/Users

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "bob.belcher@strongdm.com",
  "name": {
    "givenName": "Bob",
    "familyName": "Belcher",
    "middleName": "Jay",
    "honorificPrefix": "Mr.",
    "honorificSuffix": "III",
    "formatted": "Mr. Bob Jay Belcher III"
  },
  "emails": [
    {
      "primary": true,
      "value": "bob.belcher@strongdm.com",
      "display": "primary email",
      "type": "work"
    },
    {
      "primary": false,
      "value": "bob.belcher@example.com",
      "type": "personal"
    }
  ],
  "x509Certificates": [
    {
      "value": "aGVsbG8gd29ybGQK",
      "display": "display",
      "primary": true
    },
    {
      "value": "aGVsbG8gd29ybGQK",
      "display": "display2"
    }
  ],
  "roles": [
    {
      "value": "value",
      "display": "display",
      "primary": true,
      "type": "one"
    },
    {
      "value": "value",
      "display": "display",
      "type": "two"
    }
  ],
  "entitlements": [
    {
      "value": "value",
      "display": "display",
      "primary": true,
      "type": "one"
    },
    {
      "value": "value",
      "display": "display",
      "type": "two"
    }
  ],
  "displayName": "Bob Belcher",
  "nickName": "Bobby",
  "profileUrl": "https://login.example.com/bobbelcher",
  "title": "Vice President",
  "preferredLanguage": "en-US",
  "timezone": "America/Los_Angeles",
  "locale": "en-US",
  "externalId": "701984",
  "groups": [],
  "password": "t1meMa$heen",
  "active": true,
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "701984",
    "costCenter": "4130",
    "organization": "Universe",
    "division": "Research and Development",
    "department": "Operations",
    "manager": {
      "value": "26118915-6090-4610-87e4-49d8ca9f808d",
      "$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d"
    }
  }
}

Simplified example request

For compatibility with certain clients, the roles and entitlements attributes may be added to a user in two formats: the canonical method and the simplified method.

The canonical method is shown in the example request with all supported attributes.

The simplified method of adding roles and entitlements to a user is shown in the following Create User example request.

POST app.strongdm.com/provisioning/generic/v2/Users

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    ...
    "roles": [
        "role1",
        "role2",
        "role3"
    ],
    "entitlements": [
        "ent1",
        "ent2",
        "ent3"
    ]
}

Response

Example success response

(Status 201)
{
  "active": true,
  "displayName": "Bob Belcher",
  "emails": [
    {
      "display": "primary email",
      "primary": true,
      "type": "work",
      "value": "bob.belcher@strongdm.com"
    },
    {
      "display": "",
      "type": "personal",
      "value": "bob.belcher@example.com"
    }
  ],
  "entitlements": [
    {
      "display": "display",
      "primary": true,
      "type": "one",
      "value": "value"
    },
    {
      "display": "display",
      "primary": false,
      "type": "two",
      "value": "value"
    }
  ],
  "externalId": "701984",
  "groups": [],
  "id": "a-412950b063569179",
  "locale": "en-US",
  "meta": {
    "resourceType": "User",
    "location": "Users/a-412950b063569179"
  },
  "name": {
    "familyName": "Belcher",
    "formatted": "Mr. Bob Jay Belcher III",
    "givenName": "Bob",
    "honorificPrefix": "Mr.",
    "honorificSuffix": "III",
    "middleName": "Jay"
  },
  "nickName": "Bobby",
  "preferredLanguage": "en-US",
  "profileUrl": "https://login.example.com/bobbelcher",
  "roles": [
    {
      "display": "display",
      "primary": true,
      "type": "one",
      "value": "value"
    },
    {
      "display": "display",
      "primary": false,
      "type": "two",
      "value": "value"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "timezone": "America/Los_Angeles",
  "title": "Vice President",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "costCenter": "4130",
    "department": "Operations",
    "division": "Research and Development",
    "employeeNumber": "701984",
    "manager": {
      "$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d",
      "displayName": "26118915-6090-4610-87e4-49d8ca9f808d",
      "value": "26118915-6090-4610-87e4-49d8ca9f808d"
    },
    "organization": "Universe"
  },
  "userName": "bob.belcher@strongdm.com",
  "userType": "user",
  "x509Certificates": [
    {
      "display": "display",
      "primary": true,
      "type": "",
      "value": "aGVsbG8gd29ybGQK"
    },
    {
      "display": "display2",
      "primary": false,
      "type": "",
      "value": "aGVsbG8gd29ybGQK"
    }
  ]
}

Example response if there was a conflicting email

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "scimType": "uniqueness",
  "detail": "One or more of the attribute values are already in use or are reserved.",
  "status": "409"
}

Example response if there was no email

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail": "could not create user: cannot create user: invalid operation: email cannot be blank",
  "status": "400"
}