Skip to main content

SCIM Users API

The SCIM Users API is based on the open standard System for Cross-domain Identity Management (SCIM): Protocol 1.1. SCIM is an open standard used for automating the exchange of user identity information between identity domains or IT systems. Its purpose is to facilitate and ease the management of user identities in cloud based applications. BigPanda uses JSON-based formats for SCIM.

SCIM Users

Authentication

All BigPanda APIs require Bearer Token Authorization in the call headers.

This API uses the User API Key type of Authorization token.

BigPanda recommends adding Authentication headers only in the secure tool you use to make API calls.

Example 1. Retrieve Service Provider Configuration
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.0/scim/ServiceProviderConfigs \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.0/scim/ServiceProviderConfigs \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 2. Retrieve User Schema
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.0/scim/Schemas/urn:scim:schemas:core:1.0:User \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.0/scim/Schemas/urn:scim:schemas:core:1.0:User \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 3. Retrieve all Service Provider Schemas
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.0/scim/schemas \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.0/scim/schemas \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 4. Create a user
curl --request POST \
     --url https://api.bigpanda.io/resources/v2.0/scim/Users \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "phoneNumbers": [
          {
               "value": "+1-555-555-5555",
               "type": "home"
          }
     ],
     "roles": [
          "user"
     ],
     "userName": "[email protected]",
     "displayName": "Becky Sterling",
     "password": "Password!123",
     "active": true
}
'
curl --request POST \
     --url https://eu-api.bigpanda.io/resources/v2.0/scim/Users \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "phoneNumbers": [
          {
               "value": "+1-555-555-5555",
               "type": "home"
          }
     ],
     "roles": [
          "user"
     ],
     "userName": "[email protected]",
     "displayName": "Becky Sterling",
     "password": "Password!123",
     "active": true
}
'


Example 5. Retrieve a user by ID
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.0/scim/Users/5f82d3495558352a180e51cb \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.0/scim/Users/5f82d3495558352a180e51cb \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 6. Retrieve all users
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.0/scim/Users?sortBy=userName&filter=active eq true \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.0/scim/Users?sortBy=userName&filter=active eq true \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 7. Update a user
curl --request PATCH \
     --url https://api.bigpanda.io/resources/v2.0/scim/Users/628ed6b59c58cc555125551e \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "phoneNumbers": [
          {
               "value": "+1-555-555-5555",
               "type": "home"
          }
     ],
     "roles": [
          "user"
     ],
     "displayName": "Becky Sterling",
     "active": true
}
'
curl --request PATCH \
     --url https://eu-api.bigpanda.io/resources/v2.0/scim/Users/628ed6b59c58cc555125551e \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "phoneNumbers": [
          {
               "value": "+1-555-555-5555",
               "type": "home"
          }
     ],
     "roles": [
          "user"
     ],
     "displayName": "Becky Sterling",
     "active": true
}
'


Example 8. Delete a user
curl --request DELETE \
     --url https://api.bigpanda.io/resources/v2.0/scim/Users/628ed6b59c58cc555125551e \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
                "active": false}
'
curl --request DELETE \
     --url https://eu-api.bigpanda.io/resources/v2.0/scim/Users/628ed6b59c58cc555125551e \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
                "active": false}
'


Filtering Results

When retrieving all users, all users in the system will be returned by default, including inactive users. Inactive users are defined as any user who has been deleted.

Add a filter to the endpoint call to restrict returns based on the values of several standard fields.

Filter Syntax:

/scim/Users?filter={field} {SCIM operator} {filter value}

Filters can only apply to a subset of attribute fields within the user object:

  • displayName

  • userName

  • active

All SCIM operators are supported. See the SCIM Parameters documentation for details on available operators.

For example, a filter to retrieve only active users:

https://api.bigpanda.io/resources/v2.0/scim/Users?filter=active eq true

Sort Results

By default, retrieve users results are returned in ascending order, by active field.

Add a sort field and order to the endpoint call to change the order results are listed.

Sort Syntax:

/scim/Users?sortBy={field}&sortOrder={ascending/descending}

SortBy Fields include:

  • id

  • userName

  • displayName

  • active

SortOrder is alphanumeric for id, userName, displayName. True, then false for active. SortOrder options are:

  • ascending

  • descending

Examples:

  • https://api.bigpanda.io/resources/v2.0/scim/Users?sortBy=userName

  • https://api.bigpanda.io/resources/v2.0/scim/Users?sortBy=id&sortOrder=descending

Pagination

By default, the retrieve users call returns the first 1000 users in the list.

Pagination parameters can be used together to "page through" large numbers of returns.

Pagination Syntax:

/scim/Users?startIndex={return #}&count={# of returns}

Example:

To retrieve the first 10 users, set the startIndex to 1, and the count to 10

https://api.bigpanda.io/resources/v2.0/scim/Users?startIndex=1&count=10

To then query the next set of 10, change the startIndex to 11, and send another call.

Pagination

Pagination is not session based. A request for a list of 10 users beginning with a startIndex of 1 may return different results when repeated as a user in the original result could be deleted or new ones could be added in-between requests.

In this section: