Rate this page

User Profile

The user profile endpoint exposes user attributes from the Ping Identity Data Governance Broker’s user store as SCIM resources.

Create a user

POST /scim/v2/Users

A new user resource is created using the HTTP POST method, providing a complete representation of the resource in the request body. Read-only attributes such as meta may be omitted. If the request is successful, the Data Governance Broker will return a response with a status code of 201, with the resource’s canonical URI as the value of the Location header.

Example request:

POST /scim/v2/Users HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 488
Content-Type: application/scim+json
Host: example.com:443

{
    "emails": [
        {
            "primary": true, 
            "type": "work", 
            "value": "pat.conley@runciter.com"
        }
    ], 
    "name": {
        "familyName": "Conley", 
        "formatted": "Pat Conley", 
        "givenName": "Pat"
    }, 
    "password": "valis", 
    "schemas": [
        "urn:pingidentity:schemas:User:1.0",
        "urn:pingidentity:schemas:sample:profile:1.0"
    ], 
    "urn:pingidentity:schemas:sample:profile:1.0": {
        "birthDate": "1948-07-13"
    }, 
    "userName": "pconley"
}

Example response:

HTTP/1.1 201 Created
Content-Length: 574
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 00:01:23 GMT
Location: https://example.com:443/scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4

{
    "emails": [
        {
            "primary": true, 
            "type": "work", 
            "value": "pat.conley@runciter.com"
        }
    ], 
    "id": "76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
    "meta": {
        "created": "2016-07-30T00:01:23.824Z", 
        "lastModified": "2016-07-30T00:01:23.824Z", 
        "location": "https://example.com:443/scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
        "resourceType": "Users"
    }, 
    "name": {
        "familyName": "Conley", 
        "formatted": "Pat Conley", 
        "givenName": "Pat"
    }, 
    "schemas": [
        "urn:pingidentity:schemas:sample:profile:1.0",
        "urn:pingidentity:schemas:User:1.0"
    ], 
    "urn:pingidentity:schemas:sample:profile:1.0": {
        "birthDate": "1948-07-13"
    }, 
    "userName": "pconley"
}

Search for users (GET)

GET /scim/v2/Users

A client may filter for matching User resources by performing a GET and providing a filter query parameter, as described in the Searching section. Pagination parameters may also be provided.

The response is formatted as a list response containing zero or more matching User resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

In the following example, a search is performed using specific values for name.givenName and name.familyName.

Request:

GET /scim/v2/Users?filter=name.givenName%20eq%20%22Pat%22%20and%20name.familyName%20eq%20%22Conley%22 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Type: application/scim+json
Host: example.com:443

Response:

HTTP/1.1 200 OK
Content-Length: 672
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 00:28:56 GMT

{
    "Resources": [
        {
            "emails": [
                {
                    "primary": true, 
                    "type": "work", 
                    "value": "pat.conley@runciter.com"
                }
            ], 
            "id": "76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
            "meta": {
                "created": "2016-07-30T00:28:07.507Z", 
                "lastModified": "2016-07-30T00:28:07.507Z", 
                "location": "https://example.com:443/scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
                "resourceType": "Users"
            }, 
            "name": {
                "familyName": "Conley", 
                "formatted": "Pat Conley", 
                "givenName": "Pat"
            }, 
            "schemas": [
                "urn:pingidentity:schemas:sample:profile:1.0",
                "urn:pingidentity:schemas:User:1.0"
            ], 
            "urn:pingidentity:schemas:sample:profile:1.0": {
                "birthDate": "1948-07-13"
            }, 
            "userName": "pconley"
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ], 
    "totalResults": 1
}

Search for users (POST)

POST /scim/v2/Users/.search

A client may filter for matching User resources by performing a POST against the special .search endpoint and providing a filter value, as described in the Searching section. Pagination directives may also be provided.

The response is formatted as a list response containing zero or more matching User resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

Example request:

POST /scim/v2/Users/.search HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 38
Content-Type: application/scim+json
Host: example.com:443

{
    "filter": "userName sw \"pc\""
}

Example response:

HTTP/1.1 200 OK
Content-Length: 672
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 00:02:16 GMT

{
    "Resources": [
        {
            "emails": [
                {
                    "primary": true, 
                    "type": "work", 
                    "value": "pat.conley@runciter.com"
                }
            ], 
            "id": "76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
            "meta": {
                "created": "2016-07-30T00:01:23.824Z", 
                "lastModified": "2016-07-30T00:01:23.824Z", 
                "location": "https://example.com:443/scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
                "resourceType": "Users"
            }, 
            "name": {
                "familyName": "Conley", 
                "formatted": "Pat Conley", 
                "givenName": "Pat"
            }, 
            "schemas": [
                "urn:pingidentity:schemas:sample:profile:1.0",
                "urn:pingidentity:schemas:User:1.0"
            ], 
            "urn:pingidentity:schemas:sample:profile:1.0": {
                "birthDate": "1948-07-13"
            }, 
            "userName": "pconley"
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ], 
    "totalResults": 1
}

Retrieve a specific user

GET /scim/v2/Users/{id}

GET /scim/v2/Me

A resource may be retrieved using HTTP GET.

Example request:

GET /scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 574
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 00:03:08 GMT

{
    "emails": [
        {
            "primary": true, 
            "type": "work", 
            "value": "pat.conley@runciter.com"
        }
    ], 
    "id": "76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
    "meta": {
        "created": "2016-07-30T00:01:23.824Z", 
        "lastModified": "2016-07-30T00:01:23.824Z", 
        "location": "https://example.com:443/scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
        "resourceType": "Users"
    }, 
    "name": {
        "familyName": "Conley", 
        "formatted": "Pat Conley", 
        "givenName": "Pat"
    }, 
    "schemas": [
        "urn:pingidentity:schemas:sample:profile:1.0", 
        "urn:pingidentity:schemas:User:1.0"
    ], 
    "urn:pingidentity:schemas:sample:profile:1.0": {
        "birthDate": "1948-07-13"
    }, 
    "userName": "pconley"
}

Replace all attributes of a specific user

PUT /scim/v2/Users/{id}

PUT /scim/v2/Me

The HTTP PUT method can be used to do a full replace of an existing resource. Typically, you would first GET the resource, make any desired changes, then PUT the changed resource to the same URI.

Example request:

PUT /scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 679
Content-Type: application/scim+json
Host: example.com:443

{
    "addresses": [
        {
            "country": "US", 
            "locality": "New York", 
            "postalCode": "10020", 
            "primary": true, 
            "region": "NY", 
            "type": "home"
        }
    ], 
    "emails": [
        {
            "primary": true, 
            "type": "work", 
            "value": "pat.conley@runciter.com"
        }
    ], 
    "name": {
        "familyName": "Conley", 
        "formatted": "Pat Conley", 
        "givenName": "Pat"
    }, 
    "schemas": [
        "urn:pingidentity:schemas:User:1.0",
        "urn:pingidentity:schemas:sample:profile:1.0"
    ], 
    "urn:pingidentity:schemas:sample:profile:1.0": {
        "birthDate": "1948-07-13"
    }, 
    "userName": "pconley"
}

Example response:

HTTP/1.1 200 OK
Content-Length: 691
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 00:04:08 GMT

{
    "addresses": [
        {
            "country": "US", 
            "locality": "New York", 
            "postalCode": "10020", 
            "primary": true, 
            "region": "NY", 
            "type": "home"
        }
    ], 
    "emails": [
        {
            "primary": true, 
            "type": "work", 
            "value": "pat.conley@runciter.com"
        }
    ], 
    "id": "76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
    "meta": {
        "created": "2016-07-30T00:01:23.824Z", 
        "lastModified": "2016-07-30T00:04:08.529Z", 
        "location": "https://example.com:443/scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
        "resourceType": "Users"
    }, 
    "name": {
        "familyName": "Conley", 
        "formatted": "Pat Conley", 
        "givenName": "Pat"
    }, 
    "schemas": [
        "urn:pingidentity:schemas:sample:profile:1.0", 
        "urn:pingidentity:schemas:User:1.0"
    ], 
    "urn:pingidentity:schemas:sample:profile:1.0": {
        "birthDate": "1948-07-13"
    }, 
    "userName": "pconley"
}

Modify one or more attributes of a specific user

PATCH /scim/v2/Users/{id}

PATCH /scim/v2/Me

The PATCH method, an alternative to PUT, is used to add, modify, or remove one or more specific attributes. Unlike PUT, a complete representation is not specified.

PATCH requests always include an Operations attribute, which is an array of the changes to make.

Field Type Required? Description
schemas array yes The SCIM schema of the session resource. Always has the value urn:ietf:params:scim:api:messages:2.0:PatchOp.
Operations array yes An array of modification operations to perform on the resource.

Each modification operation contains the following fields:

Field Type Required? Description
op string yes Specifies the type of modification. Valid values are add, remove, and replace.
path string The attribute path targeted by the operation. If unspecified, then the root of the resource is targeted. To target a specific member of a multivalued complex attribute when performing a replace, the attribute path may include a filter, such as addresses[type eq "work"]. A sub-attribute may be targeted using a dotted ‘attribute.sub-attribute’ notation, such as addresses[type eq "work"].value.
value any The attribute value to set when the op value is add or replace. May not be provided when the op value is remove. Any SCIM data type may potentially be used; the validity of the value is dependent on the path.

The combination of op, path, and value gives the client a tremendous amount of expressive power in forming varied modification requests. Because the path used may potentially select any node of the resource, the client must take care to specify a value of the appropriate type. For example, the path addresses[type eq "work"] selects the member of a multivalued complex attribute, so the corresponding value must be an object. The path addresses[type eq "work"].value, meanwhile, selects a specific sub-attribute of the same object, and its corresponding value must be a string.

The SCIM PATCH request format is described in detail by RFC 7644.

The following example replaces the value of a sub-attribute of a complex attribute.

Request:

PATCH /scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 187
Content-Type: application/scim+json
Host: example.com:443

{
    "Operations": [
        {
            "op": "replace", 
            "path": "name.familyName", 
            "value": "Chip"
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}

Response:

HTTP/1.1 200 OK
Content-Length: 572
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 00:11:37 GMT

{
    "emails": [
        {
            "primary": true, 
            "type": "work", 
            "value": "pat.conley@runciter.com"
        }
    ], 
    "id": "76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
    "meta": {
        "created": "2016-07-30T00:05:29.968Z", 
        "lastModified": "2016-07-30T00:11:37.147Z", 
        "location": "https://example.com:443/scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
        "resourceType": "Users"
    }, 
    "name": {
        "familyName": "Chip", 
        "formatted": "Pat Conley", 
        "givenName": "Pat"
    }, 
    "schemas": [
        "urn:pingidentity:schemas:sample:profile:1.0", 
        "urn:pingidentity:schemas:User:1.0"
    ], 
    "urn:pingidentity:schemas:sample:profile:1.0": {
        "birthDate": "1948-07-13"
    }, 
    "userName": "pconley"
}

The following example adds a member to the complex multivalued emails attribute without explicitly setting a path.

Request:

PATCH /scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 273
Content-Type: application/scim+json
Host: example.com:443

{
    "Operations": [
        {
            "op": "add", 
            "value": {
                "emails": [
                    {
                        "type": "home", 
                        "value": "pat@gmail.com"
                    }
                ]
            }
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}

Response:

HTTP/1.1 200 OK
Content-Length: 614
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 00:08:38 GMT

{
    "emails": [
        {
            "primary": true, 
            "type": "work", 
            "value": "pat.conley@runciter.com"
        }, 
        {
            "type": "home", 
            "value": "pat@gmail.com"
        }
    ], 
    "id": "76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
    "meta": {
        "created": "2016-07-30T00:05:29.968Z", 
        "lastModified": "2016-07-30T00:08:38.583Z", 
        "location": "https://example.com:443/scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
        "resourceType": "Users"
    }, 
    "name": {
        "familyName": "Conley", 
        "formatted": "Pat Conley", 
        "givenName": "Pat"
    }, 
    "schemas": [
        "urn:pingidentity:schemas:sample:profile:1.0", 
        "urn:pingidentity:schemas:User:1.0"
    ], 
    "urn:pingidentity:schemas:sample:profile:1.0": {
        "birthDate": "1948-07-13"
    }, 
    "userName": "pconley"
}

The following example removes a specific value of the complex multivalued emails attribute by providing a filter in the path.

Request:

PATCH /scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 172
Content-Type: application/scim+json
Host: example.com:443

{
    "Operations": [
        {
            "op": "remove", 
            "path": "emails[type eq \"home\"]"
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}

Response:

HTTP/1.1 200 OK
Content-Length: 574
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 00:10:09 GMT

{
    "emails": [
        {
            "primary": true, 
            "type": "work", 
            "value": "pat.conley@runciter.com"
        }
    ], 
    "id": "76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
    "meta": {
        "created": "2016-07-30T00:05:29.968Z", 
        "lastModified": "2016-07-30T00:10:09.219Z", 
        "location": "https://example.com:443/scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4", 
        "resourceType": "Users"
    }, 
    "name": {
        "familyName": "Conley", 
        "formatted": "Pat Conley", 
        "givenName": "Pat"
    }, 
    "schemas": [
        "urn:pingidentity:schemas:sample:profile:1.0", 
        "urn:pingidentity:schemas:User:1.0"
    ], 
    "urn:pingidentity:schemas:sample:profile:1.0": {
        "birthDate": "1948-07-13"
    }, 
    "userName": "pconley"
}

Delete a specific user

DELETE /scim/v2/Users/{id}

DELETE /scim/v2/Me

A resource is deleted using the HTTP DELETE method. An empty response with the 204 status code is returned upon success.

Example request:

DELETE /scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 0
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 204 No Content
Date: Sat, 30 Jul 2016 00:05:03 GMT