Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo
back

SCIM API for STA

SCIM user management API

search

SCIM user management API

SCIM user management API

The SCIM API for STA includes operations for retrieving, creating, updating, and deleting users. Users include the common attributes, core attributes, and the STA custom attributes.

  • Core user schema: urn:ietf:params:scim:schemas:core:2.0:User

  • STA custom user schema: urn:ietf:params:scim:schemas:extension:stauserextension:2.0:User

The SCIM user schema includes groups, but the group information is not returned in the response from STA.

See also the SCIM API limitations.

Retrieve users (GET)

GET /tenants/{tenantCode}/scim/v2/users

Retrieve a paginated list of users, with a default of 20 users per page. Control the start and number of users per page with the startIndex and itemsPerPage parameters. For the first page of results, use startIndex = 1.

To reduce the number of returned results, add an eq or and filter. For example:

  • GET /tenants/{tenantCode}/scim/v2/users?filter=username eq "john"

  • GET /tenants/{tenantCode}/scim/v2/users?filter=active eq true

  • GET /tenants/{tenantCode}/scim/v2/users?filter=active eq true and name.familyName eq "Smith"

The search filter can query the following attributes:

  • userName

  • name.givenName

  • name.familyName

  • emails.value

  • active

  • displayName

  • externalId

  • urn:ietf:params:scim:schemas:extension:stauserextension:2.0:user:alias1

  • urn:ietf:params:scim:schemas:extension:stauserextension:2.0:user:alias2

  • urn:ietf:params:scim:schemas:extension:stauserextension:2.0:user:alias3

  • urn:ietf:params:scim:schemas:extension:stauserextension:2.0:user:alias4

  • urn:ietf:params:scim:schemas:extension:stauserextension:2.0:user:userPrincipalName

  • urn:ietf:params:scim:schemas:extension:stauserextension:2.0:user:immutableId

  • urn:ietf:params:scim:schemas:extension:stauserextension:2.0:user:custom1

  • urn:ietf:params:scim:schemas:extension:stauserextension:2.0:user:custom2

  • urn:ietf:params:scim:schemas:extension:stauserextension:2.0:user:custom3

  • phoneNumbers.value

  • country

  • postalCode

  • region

  • locality

  • streetAddress

If users are added or removed by a concurrent operation while paging through a list of results, some users may be missed.

The response is a JSON list of all the users for the specified virtual server (tenantCode).

Sample response

{
  "totalResults": 12,
  "itemsPerPage": 2,
  "startIndex": 1,
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "resources": [
    {
      "schemas": [
          "urn:ietf:params:scim:schemas:core:2.0:User",
          "urn:ietf:params:scim:schemas:extension:stauserextension:2.0:User"
      ],
      "id": "08D88B07D109CC9801556BF0209100000001",
      "externalId": "123456",
      "userName": "sas1",
      "name": {
        "formatted": "Terry Smith",
        "familyName": "Smith",
        "givenName": "Terry"
      },
      "displayName": "sas1",
      "emails": [
        {
          "value": "sas1@sas.com",
          "primary": true
        }
      ],
      "addresses": [
        {
          "streetAddress": "123 Main Street",
          "locality": "Ottawa",
          "region": "Ontario",
          "postalCode": "A1A 1B2",
          "country": "Canada",
          "primary": true
        }
      ],
      "phoneNumbers": [
        {
          "value": "613-555-1234",
          "type": "mobile",
          "primary": true
        }
      ],
      "active": true,
      "urn:ietf:params:scim:schemas:extension:stauserextension:2.0:User": {
        "alias1": "alias1",
        "alias2": "alias2",
        "custom1": "custom1",
        "custom2": "custom2",
        "custom3": "custom3",
        "isSynchronized": false,
        "immutableId": "2ad445a9-db75-4c6e-b694-7b55a527ca85"
        "userPrincipalName": "terry.smith@sas.com"
      },
      "meta": {
        "resourceType": "User",
        "created": "2020-11-17T19:48:16.153Z",
        "lastModified": "2021-02-25T15:20:20.33Z",
        "location":     "http://localhost:5000/tenants/6AFDW7GR6I/scim/v2/users/08D88B07D109CC9801556BF0209100000001"
      }
    },
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:stauserextension:2.0:User"
      ],
      "id": "08D8D266AC82F1E701E9CF60937F00000001",
      "externalId": "234567",
      "userName": "mike",
      "name": {
        "formatted": "Mike Smith",
        "familyName": "Smith",
        "givenName": "Mike"
      },
      "displayName": "mike",
      "emails": [
        {
          "value": "mike@sas.com",
          "primary": true
        }
      ],
      "addresses": [
        {
          "streetAddress": "123 Fake Street",
          "locality": "Ottawa",
          "region": "Ontario",
          "postalCode": "K2E 1T2",
          "country": "Canada",
          "primary": true
        }
      ],
      "phoneNumbers": [
        {
          "value": "613-555-1234",
          "type": "mobile",
          "primary": true
        }
      ],
      "active": true,
      "urn:ietf:params:scim:schemas:extension:stauserextension:2.0:User": {
        "alias1": "Mikey",
        "alias2": "Michael",
        "custom1": "mike",
        "custom2": "michael",
        "custom3": "mikey",
        "isSynchronized": false,
        "immutableId": "3ad325a2-db68-8c3e-b672-6b79a764ca28"
        "userPrincipalName": "mike.smith@sas.com"
      },
      "meta": {
        "resourceType": "User",
        "created": "2021-02-16T15:36:09.58Z",
        "lastModified": "2021-02-24T18:03:48.48Z",
        "location" "http://localhost:5000/tenants/6AFDW7GR6I/scim/v2/users/08D8D266AC82F1E701E9CF60937F00000001"
      }
    }
  ]
}

Errors

Error Cause
400 Bad request Bad request
401 Unauthorized The apikey authorization header is missing or invalid.
404 Not Found The tenantCode is incorrect.
500 Internal server error The server was unable to process the request.

Retrieve a specific user (GET)

GET /tenants/{tenantCode}/scim/v2/users/{userIdentifier}

Returns the details for the specified user, in SCIM format.

Sample response

200 OK
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:stauserextension:2.0:User"
    ],
    "id": "88D8E885A0C7D520D1D1FC42E9B900000002",
    "externalId": "123456",
        "userName": "karla",
        "name": {
          "formatted": "Karla Herzolf",
          "familyName": "Herzolf",
          "givenName": "Karla"
        },
        "displayName": "karla",
        "emails": [
          {
              "value": "kh@gmail.com",
              "primary": true
          }
      ],
      "addresses": [
        {
            "streetAddress": "123 Main Street",
            "locality": "Ottawa",
            "region": "Ontario",
            "postalCode": "A1A 1A1",
            "country": "Canada",
            "primary": true
        }
      ],
      "phoneNumbers": [
          {
              "value": "6135551212",
              "type": "mobile",
              "primary": true
          }
      ],
      "active": true,
      "urn:ietf:params:scim:schemas:extension:stauserextension:2.0:User": {
          "alias1": "SCIM ALIAS 1",
          "alias2": "SCIM ALIAS 2",
          "custom1": "SCIM CUSTOM 1",
          "custom2": "SCIM CUSTOM 2",
          "custom3": "SCIM CUSTOM 3",
          "isSynchronized": false,
          "immutableId": "3ad446a8-db87-8c2e-b294-7b67a377ca37"
          "userPrincipalName": "karla.herzolf@sas.com"
      },
      "groups": [
          {
              "value": "16777220",
              "$ref": "https://api.stademo.com/tenants/ABCDE12345/scim/v2/groups/16777220",
              "display": "sales"
              "type": "direct"
          },
          {
              "value": "50331651",
              "$ref": "https://api.stademo.com/tenants/ABCDE12345/scim/v2/groups/50331651",
              "display": "accounting"
              "type": "direct"
          }
      ],
      "meta": {
          "resourceType": "User",
          "created": "2021-03-16T14:13:09.867Z",
          "lastModified": "2021-03-25T13:22:47.26Z",
          "location": "https://example.com/tenants/ABCDE12345/scim/v2/users/88D8E885A0C7D520D1D1FC42E9B900000002"
      }
  }

Errors

Error Cause
400 Bad Request The user object ID is not hex-encoded.
401 Unauthorized The apikey authorization header is missing or invalid.
404 Not Found The tenantCode or user ID is incorrect.
500 Internal server error The server was unable to process the request.

Create a user (POST)

POST /tenants/{tenantCode}/scim/v2/users/

By default, users that are created with the SCIM API are internal users, unless they are specified as synced users in the request.

The request must include the userName field.

Group membership cannot be updated with the create a user request. To update group membership, use the update (PUT) group request or replace (PATCH) group request.

When the request is successful, the response lists the user details and the meta.location field includes a link to the user details.

Sample request

{
    "userName": "jalbert",
    "name": {
        "familyName": "Albert",
        "givenName": "Jim"
    },
    "emails": [
        {
        "value": "jalbert@example.com"
        }
    ],
    "phoneNumbers" : [
        {
            "value": "6135551212",
            "type": "mobile"
        }
    ],
    "urn:ietf:params:scim:schemas:extension:stauserextension:2.0:User": {
        "alias1": "jamesAlbert",
        "custom1": "custom value",
        "isSynchronized": false
    }
}

Sample response

201 Created
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:stauserextension:2.0:User"
    ],
    "name": {
        "familyName": "Albert",
        "givenName": "Jim"
    },
    "emails": [
        {
        "value": "jalbert@example.com"
        }
    ],
    "phoneNumbers" : [
        {
            "value": "6135551212",
            "type": "mobile",
            "primary": "true"
        }
    ],
    "urn:ietf:params:scim:schemas:extension:stauserextension:2.0:User": {
        "alias1": "jamesAlbert",
        "custom1": "custom value",
        "isSynchronized": false
    },
    "meta": {
        "resourceType": "User",
        "created": "2021-03-16T14:13:09.867Z",
        "lastModified": "2021-03-25T13:22:47.26Z",
        "location": "https://example.com/tenants/ABCDE12345/scim/v2/users/88D8E885A0C7D520D1D1FC42E9B900000002"
    }
}

Errors

Error Cause
400 Bad Request One or more of the required attributes is missing. If more than one required attribute is missing, only the first one is included in the error response.
401 Unauthorized The apikey authorization header is missing or invalid.
404 Not Found The tenantCode or user ID is incorrect.
409 Conflict The requested userName or aliases are already in use.
500 Internal Server Error The server was unable to process the request.

Update a specific user (PATCH)

PATCH /tenants/{tenantCode}/scim/v2/users/{userIdentifier}

Update one or more attributes of a user using a sequence of operations to add, remove, or replace values. The list of operations is passed to the API in the JSON body of the request.

You can find excellent information about patch operations.

You can patch simple attributes, complex attributes, and complex multi-valued attributes.

The body of each request can contain the following attributes:

  • schemas: The URI value is:

    urn:ietf:params:scim:api:messages:2.0:PatchOp

  • Operations: The value is an array of one or more patch operations:

    • op: Each patch operation object must have exactly one op member. The op value indicates the operation to perform and can be one of add, remove, or replace.

    • path: The path contains the attribute path for the field that is being patched.

      To address attributes and sub-attributes, use path filters. Only the eq operator is supported for the path filter with patch. With the eq filter, paths can be complex.

    • value: This is the new value for the field that is being patched. The value can be a quoted value, or it can be a JSON object that contains the sub-attributes of the complex attribute. The value is required for add and replace operations.

      To reset the value of a property, use an empty string ( “” ). However, you cannot reset the following fields to empty:

      • userName

      • emails.value

The mobile phone number can be patched, but the work phone number cannot.

Sample request

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "name",
      "value": {
          "givenName": "Martin",
          "familyName": "Freeman"
    },
    {
      "op": "replace",
      "path": "name.familyName",
      "value": "NewLastName"
    },
    {
      "op": "replace",
      "path": "userPrincipalName",
      "value": "mike.smith@sas.com"
    },
    {
      "op": "remove",
      "path": "addresses[type eq \"work\"].postalCode"
    }
  ]
}

Sample response

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:stauserextension:2.0:User"
  ],
  "id": "08D91F624E0CD34D010D348D78D800000001",
  "externalId": "123456",
  "userName": "test",
  "name": {
    "formatted": "test NewLastName",
    "familyName": "NewLastName",
    "givenName": "test"
  },
  "displayName": "test",
  "emails": [
    {
      "value": "test@sas.com",
      "primary": true
    }
  ],
  "addresses": [
    {
      "streetAddress": "123 Fake St",
      "locality": "Ottawa",
      "region": "ON",
      "country": "Canada",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "613-555-1234",
      "type": "mobile",
      "primary": true
    }
  ],
  "active": "true",
  "urn:ietf:params:scim:schemas:extension:stauserextension:2.0:User": {
    "isSynchronized": false,
    "userPrincipalName": "mike.smith@sas.com"
  },
  "meta": {
    "resourceType": "User",
    "created": "2021-05-25T13:48:52.647Z",
    "lastModified": "2021-11-10T13:32:46.6630785Z",
    "location": "http://localhost:5000/tenants/BY6XA80E9M/scim/v2/Users/08D91F624E0CD34D010D348D78D800000001"
  }
}

Errors

Error Cause
400 Bad Request Attempt to update the value of isSynchronized.
401 Unauthorized The apikey authorization header is missing or invalid.
404 Not Found The tenantCode or user object ID is incorrect.
500 Internal Server Error The server was unable to process the request.

Replace a specific user (PUT)

PUT /tenants/{tenantCode}/scim/v2/users/{userIdentifier}

Completely replaces the attributes of an existing user with the details provided in the request. If existing values are not provided, they are removed.

To avoid losing or unintentionally over-writing user data, retrieve (GET) the user before you update (PUT) the user with any changes.

Group membership cannot be updated with the update user request. To update group membership, use the update (PUT) group request.

A successful response includes the same data as Create a User, with response code 200 (OK).

Errors

Error Cause
400 Bad Request Attempt to update the value of isSynchronized.
401 Unauthorized The apikey authorization header is missing or invalid.
404 Not Found The tenantCode or user object ID is incorrect.
409 Conflict The requested userName or aliases are already in use.
500 Internal Server Error The server was unable to process the request.

Remove a specific user (DELETE)

DELETE /tenants/{tenantCode}/scim/v2/users/{userIdentifier}

Response code: 204 No Content

Errors

Error Cause

400 Bad Request

The user object ID is not hex encoded.

401 Unauthorized

The apikey authorization header is missing or invalid.
403 Forbidden
  • Cannot delete an account manager.
  • Cannot delete an operator.
  • Cannot delete your own user account.

404 Not Found

The tenantCode or user object ID is incorrect.

500 Internal Server Error

The server was unable to process the request.