Board SCIM API

The Board SCIM API service is the Board implementation of the System for Cross-domain Identity Management (SCIM) standard. SCIM is an HTTP-based protocol that makes managing identities in multi-domain and multi-system scenarios easier to support through a standardized service. SCIM allows Admins to automatically sync user accounts and permissions across multiple applications, ensuring that this information is always up to date and correct.

An important benefit of the Board SCIM API service is standardization: with it, we offer accessibility and full operability with other identity management systems, solving many identity maintenance challenges such as record tracking and on- and off-boarding. The Board SCIM API service facilitates secure identity data management and control. This API package is integrated into Board's Subscription Hub portal.

With Board’s SCIM Service APIs, you can:

  • Build integrations with supported identity management tools
  • Automate the management of your users

 

Board SCIM implementation does not support the management of Client API users created in the Subscription Hub. 
Board’s implementation uses version 2.0 of the SCIM standard.

 

Getting started

When using Board SCIM APIs you should first configure all necessary metadata that correspond to the user and group attributes used in the APIs requests. Data synchronized is stored within Board and can also be manually updated in the Subscription Hub.
For example, you may choose to synchronize a User's familyName, givenName and userName (email login) but not synchronize activeFlag. Alternatively, you may choose to store and synchronize all of that data in your internal systems.
In either case, be aware that changes made in the Subscription Hub will change the data stored in Board.

Depending on how you integrate with the SCIM APIs you may create an unexpected condition. For example, if someone gets married and you change the familyName (Last Name) in the Board Subscription Hub but not in your system of record, depending on how your integration logic is written, that change could be set back to the original familyName.

 

Configuration on Board's Subscription Hub

Before users can make requests with the SCIM APIs, the following conditions must be met:

  1. A Client API user must exist and must have the new “enable SCIM endpoint” option turned on. The Client API is required for authentication in the API requests. See the Authentication paragraph below for more information
  2. All metadata corresponding to the user and group attributes used in the APIs requests must already be created. This is done in the User Metadata section of the Subscription Hub: map the metadata fields to the corresponding SCIM attributes with the new "SCIM attribute" drop-down list.
  3. All needed Permission Groups that will be referenced in the APIs must have been created. This is done in the new "Permission Groups" section of the Subscription Hub.

    The configuration of each Permission Group is similar to the configuration of a single user in the Subscription Hub: in the Group configuration panel, you can assign roles and access permissions in a granular way for each Board Platform, as well as assign Subscription Hub administrative authorizations and define specific metadata values. 
    All these configurations will be automatically applied to users added to the Group.

    You can also set a default Permission Group: in this case, the configurations and properties defined in that Permission Group will be automatically applied to all new users created in the Subscription Hub from that point on.
    To set a Permission Group as default, select it in the table and click the "SET AS DEFAULT" button that appears on top of the table:

    To remove a Permission Group as default, select it in the table and click the "REMOVE DEFAULT" button that appears on top of the table, or define a new default Permission Group.

    There can be only one Permission Group set as default.
    If a user is created via a SCIM request and no default Permission Group is set in the Subscription Hub (or the default Permission Group is disabled), the account will be created with the "Board authentication" authentication type, but the email needed to verify the associated email address and set a password will not be sent automatically (as is the case for manually created users).
    The email needed to verify the associated email address and set a password is sent automatically when:
    - Users are added to a Permission Group which is not disabled and has the authentication type set to "Board authentication". This is also the case for default Permission Groups
    - The authentication type of a user or a non-empty Permission Group is changed from any setting to "Board authentication".

 

Authentication & API endpoints

 

Other topics

 

 

 

Authentication

To obtain an authentication token, you have to send a request which must be compliant with OAuth2 client credentials flow specifications.

To obtain the necessary authentication token, proceed as follows:

  1. Create a Client API user as explained here. The Client API user must have the new “enable SCIM endpoint” option turned on
  2. Once you have created the necessary Client API user, an authorization token must be generated before making any request. The token returned from this request must be used to manage the authentication in the API requests.
    The authentication must comply with OAuth2 client credentials flow specifications.

    To obtain the authorization token, you need to set the following additional parameters:

    • Grant Type: "Client Credentials"
    • Access Token URL: https://your-subscription-hub-url/connect/token
    • Scope: "board-scim"
    • Client Authentication: "Send client credentials in body"

  3. Pass the token to the SCIM API through a request as shown below.


Example

GET https://your-subscription-hub-url/scim/Users/<user id here>

 

Request header

Header Details

Authorization: Bearer <id token from step 2>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token

 

Request parameters

none

 

Curl example

curl -X GET -H 'Authorization: Bearer <id token here>'
https://your-subscription-hub-url/scim/Users/<user id here>

 

Response body

If your Authentication passes, you'll receive the response for the API you called.

 

 

 

 

Get supported SCIM capabilities

Use this call to retrieve the supported SCIM capabilities.

 

Request

GET /ServiceProviderConfig
    Host: https://your-subscription-hub-url/scim
    Authorization: Bearer <id token here>


Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token

 

Request parameters

none

 

Curl example

curl -X GET -H 'Authorization: Bearer <id token here>'
https://your-subscription-hub-url/scim/ServiceProviderConfig

 

Response header

Header Details

Content-Type: application/scim+json

The response body is formatted as application/scim+json

 

Response body

Example:

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
    ],
    "documentationUri": "documentationURL",
    "patch": {
        "supported": true
    },
    "bulk": {
        "supported": false
    },
    "filter": {
        "supported": true,
        "maxResults": 200
    },
    "changePassword": {
        "supported": false
    },
    "sort": {
        "supported": true
    },
    "authenticationSchemes": [
        {
            "name": "OAuth v2.0",
            "description": "Authentication scheme using the OAuth standard.",
            "specUri": "http://tools.ietf.org/html/rfc6749",
            "type": "oauth2",
            "primary": true
        }
    ],
    "meta": {
        "location": "https://your-subscription-hub-url/scim/ServiceProviderConfig",
        "resourceType": "ServiceProviderConfig",
        "created": "2023-05-04T00:00:00Z",
        "lastModified": "2023-05-04T00:00:00Z"
    }
}

 

 

 

Get resource types

Use this call to retrieve all of the resource types supported.

 

Request

GET /ResourceTypes
    Host: https://your-subscription-hub-url/scim
    Authorization: Bearer <id token here>


Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token

 

Request parameters

none

 

Curl example

curl -X GET -H 'Authorization: Bearer <id token here>'
https://your-subscription-hub-url/scim/ResourceTypes

 

Response header

Header Details

Content-Type: application/scim+json

The response body is formatted as application/scim+json

 

Response body

Example:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 50,
    "Resources": [
        {
            "id": "urn:ietf:params:scim:schemas:core:2.0:User",
            "name": "User",
            "description": "Resource type for Users. Users are things that can login.",
            "endpoint": "/Users",
            "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
            "schemaExtensions": [
                {
                    "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
                }
            ],
            "meta": {
                "location": "https://your-subscription-hub-url/scim/Users",
                "resourceType": "ResourceType"
            }
        },
        {
            "id": "urn:ietf:params:scim:schemas:core:2.0:Group",
            "name": "Group",
            "description": "Resource type for Groups. Group govern some access and sharing.",
            "endpoint": "/Groups",
            "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
            "meta": {
                "location": "https://your-subscription-hub-url/scim/Groups",
                "resourceType": "ResourceType"
            }
        }
    ]
}

 

 

 

Get resource schema

Use this call to obtain the supported attributes for resources (e.g., User) and the attribute meta-data.


Request

GET /Schemas
    Host: https://your-subscription-hub-url/scim
    Authorization: Bearer <id token here>


Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token

 

Curl example

curl -X GET -H 'Authorization: Bearer <id token here>'
https://your-subscription-hub-url/scim/Schemas

 

Request parameters

None

 

Response header

Header Details

Content-Type: application/scim+json

The response body is formatted as application/scim+json

 


Response body

Use the location value to retrieve the attribute meta-data used by the API.

Example:

{
    "totalResults": 3,
    "itemsPerPage": 3,
    "startIndex": 1,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "resources": [
        {
            "id": "urn:ietf:params:scim:schemas:core:2.0:User",
            "name": "User",
            "description": "User Account",
            "meta": {
                "resourceType": "Schema",
                "location": "https://your-subscription-hub-url/scim/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
            }
        },
        {
            "id": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "name": "EnterpriseUser",
            "description": "Enterprise User",
            "meta": {
                "resourceType": "Schema",
                "location": "https://your-subscription-hub-url/scim/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            }
        },
        {
            "id": "urn:ietf:params:scim:schemas:core:2.0:Group",
            "name": "Group",
            "description": "Group",
            "meta": {
                "resourceType": "Schema",
                "location": "https://your-subscription-hub-url/scim/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
            }
        }
    ]
}

 

 

 

Get single user details

Use this endpoint to retrieve all information of a single user.

 

Request

GET /Users/{id}
    Host: https://your-subscription-hub-url/scim
    Authorization: Bearer <id token here>

 

Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token

 

Curl example

curl -X GET -H 'Authorization: Bearer <id token here>'
https://your-subscription-hub-url/scim/Users/{id}

 

Response header

Header Details

Content-Type: application/scim+json

The response body is formatted as application/scim+json

 


Response body

Example:

{
    "userName": "johndoe@example.com",
    "name": {
        "formatted": "John Doe",
        "familyName": "Doe",
        "givenName": "John"
    },
    "displayName": "John Doe",
    "preferredLanguage": "it-IT",
    "locale": "it-IT",
    "active": true,
    "emails": [
        {
            "value": "johndoe@example.it",
            "type": "work",
            "primary": true
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "meta": {
        "resourceType": "User",
        "location": "https://your-subscription-hub-url/scim/users/c98b9447-1383-4bae-8133-f7c1bf8b3c96"
    },
    "id": "c98b9447-1383-4bae-8133-f7c1bf8b3c96",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "Human Resources"
    }
}

 

 

 

Get multiple users

Use this endpoint to search for users.

 

Request

Use a filter and provide the pagination parametersstartIndex and count to retrieve multiple users.

GET /Users/?filter=displayName Eq "Samuel"&startIndex=1&count=100
    Host: https://your-subscription-hub-url/scim
    Authorization: Bearer <id token here>

 

Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token

 

Request parameters

Pagination parameters

Parameter Details

startIndex

The pagination index to start with for the response

Default: 1
count

The pagination count per response

 

Filter parameters

Parameter Details

filter

A filter expression to restrict the result set in the form of <field> <operator> <value>

Example: displayName Eq “Lemuel”

Expressions may be separated with and, or or (  ) (not is not supported)

 

Filter fields

Field Details

id

Supported

externalId

Supported

userName

Supported

displayName

Supported

name.formatted

Supported

locale

Supported. Values must be formatted according to the RFC 4646 standard, "Tags for the Identification of Languages", e.g. it-IT

active

Supported

email

Supported

phoneNumber

Supported

 

Filter operators

Operators are case insensitive. E.g. Ne and ne both work.

The only operators supported are those in the table below.

Operator Details

Eq

- equal

- The attribute and operator values must be identical for a match

Ne

- not equal

- The attribute and operator values are not identical

Co

- contains

- The entire operator value must be a substring of the attribute value for a match

Sw

- starts with

- The entire operator value must be at the beginning of the attribute value. This criterion is satisfied if the two strings are identical

Ew

- ends with

- The entire operator value must be a substring of the attribute value, matching at the end of the attribute value. This criterion is satisfied if the two strings are identical

 

Complex Attributes

Complex attribute filtering, for instance searching in a complex array with the [ ] notation, is not supported.

 

Curl example

curl -X GET -H 'Authorization: Bearer <id token here>'
https://your-subscription-hub-url/scim/Users?filter=displayName Eq "Samuel"&startIndex=1&count=100

 

Response header

Header Details

Content-Type: application/scim+json

The response body is formatted as application/scim+json

 

Response body

Example:

{
    "totalResults": 3,
    "itemsPerPage": 3,
    "startIndex": 1,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
        {
            "userName": "erussell@acme.corp",
            "name": {
                "formatted": "Eugen Russell",
                "familyName": "Russell",
                "givenName": "Eugen"
            },
            "displayName": "Eugen Russell",
            "locale": "en-US",
            "active": true,
            "emails": [
                {
                    "value": "erussell@acme.corp",
                    "type": "work",
                    "primary": true
                }
            ],
            "addresses": [
                {
                    "formatted": "",
                    "type": "home"
                }
            ],
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            ],
            "meta": {
                "resourceType": "User",
                "location": "https://your-subscription-hub-url/scim/users/4da5e536-de8f-4eb3-acbb-c6933886ec3e"
            },
            "id": "4da5e536-de8f-4eb3-acbb-c6933886ec3e",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "department": "IT"
            }
        },
        {
            "userName": "cfields@acme.corp",
            "name": {
                "formatted": "Caroline Fields",
                "familyName": "Fields",
                "givenName": "Caroline"
            },
            "displayName": "Caroline Fields",
            "locale": "en-US",
            "active": true,
            "emails": [
                {
                    "value": "cfields@acme.corp",
                    "type": "work",
                    "primary": true
                }
            ],
            "addresses": [
                {
                    "formatted": "",
                    "type": "home"
                }
            ],
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            ],
            "meta": {
                "resourceType": "User",
                "location": "https://your-subscription-hub-url/scim/users/5eb6594f-3313-4835-b70c-122448dc836a"
            },
            "id": "5eb6594f-3313-4835-b70c-122448dc836a",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "department": "Marketing"
            }
        },
        {
            "userName": "randerson@acme.corp",
            "name": {
                "formatted": "Ray Anderson",
                "familyName": "Anderson",
                "givenName": "Ray"
            },
            "displayName": "Ray Anderson",
            "locale": "en-US",
            "active": true,
            "emails": [
                {
                    "value": "randerson@acme.corp",
                    "type": "work",
                    "primary": true
                }
            ],
            "addresses": [
                {
                    "formatted": "",
                    "type": "home"
                }
            ],
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            ],
            "meta": {
                "resourceType": "User",
                "location": "https://your-subscription-hub-url/scim/users/6d5c231d-3409-479d-9bdb-06b35b14f743"
            },
            "id": "6d5c231d-3409-479d-9bdb-06b35b14f743",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "department": "Marketing"
            }
        }
    ]
}

 

 

Differences from the SCIM standard

  • Include/exclude query parameters are not supported
  • Supported filter query parameters, filter operators, filters fields: see tables above
  • Search is case-insensitive
  • Search with post ( /.search and /Users/.search ) is not supported

 

 

 

Add a user

Use this call to add a single user and their name details.

 

Request

POST /Users
     Host: https://your-subscription-hub-url/scim
     Authorization: Bearer <id token here>
     Accept: application/scim+json
     Content-Type: application/scim+json

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "userName": "samsmith@acme.com",
    "emails": [
        {
            "value": "samsmith@acme.com",
            "primary": true
        }
    ],
    "externalId": "ssmith",
    "active": "True",
    "name": {
        "formatted": "Sam Smith",
        "familyName": "Smith",
        "givenName": "Sam"
    },
    "displayName": "Sam Smith"
}

 

Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token
Accept: application/scim+json This call responds with a content type of application/scim+json
Content-Type: application/scim+json The response body is formatted as application/scim+json

 

User attributes

The following user attributes are system reserved and cannot be mapped to custom user metadata in the Subscription Hub.

Operator Details

id

The Board unique ID for the resourceType

userName

Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users

displayName

The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described, if known

locale

Used to indicate the User's default location for purposes of localizing items such as currency, date time format, or numerical representations. Values must be formatted according to the RFC 4646 standard, "Tags for the Identification of Languages", e.g. it-IT

active

A Boolean value indicating the User's administrative status

emails[0].value

Email addresses for the user.  The value SHOULD be canonicalized by the service provider, e.g., 'bjensen@example.com' instead of 'bjensen@EXAMPLE.COM'. Canonical value is only of 'work' type

phoneNumbers[0].value

Phone number of the User

 

The following user attributes can be mapped to custom user metadata in the Subscription Hub.

Operator Details

externalId

 The unique ID of the resource at the SCIM client. The client will use this ID to reference this resource in requests

name.familyName

 The family name of the User, or last name in most Western languages (e.g., 'Smith' given the full name 'Mr Sam Smith, II')

name.givenName

 The given name of the User, or first name in most Western languages (e.g., 'Smith' given the full name 'Mr Sam Smith, II')

name.middleName

 The middle name(s) of the User (e.g., 'Eric' given the full name 'Mr Sam E Smith, II')

name.honorificPrefix

The honorific prefix(es) of the User, or title in most Western languages (e.g., 'Ms.' given the full name 'Ms. Geena J Ross, II')
name.honorificSuffix The honorific suffix(es) of the User, or suffix in most Western languages (e.g., 'II' given the full name 'Ms. Geena J Ross, II').

nickName

 The casual way to address the user in real life, e.g., 'Bob' or 'Bobby' instead of 'Robert'. This attribute SHOULD NOT be used to represent a User's username (e.g., 'bjensen' or 'mpepperidge')

profileUrl

 A fully qualified URL pointing to a page representing the User's online profile

title

 The user's title, such as 'Vice President'

userType

 Used to identify the relationship between the organization and the user. Typical values used might be 'Contractor', 'Employee', 'Intern', 'Temp', 'External', and 'Unknown', but any value may be used

timeZone

 The User's time zone in the 'Olson' time zone database format, e.g., 'America/Los_Angeles' 

photos[0].value

 URL of a photo of the User

addresses[0].streetAddress

 The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. This attribute MAY contain newlines
addresses[0].locality The city or locality component
addresses[0].region The state or region component
addresses[0].postalCode The zip code or postal code component
addresses[0].country The country name component
entitlements[0].value The value of an entitlement. An entitlement for the User represents a thing the User has

 

Board also supports these Enterprise User extensions, which show up under the URN urn:scim:schemas:extension:enterprise:2.0.

Operator Details

employeeNumber

 Numeric or alphanumeric identifier assigned to a person, typically based on order of hire or association with an organization
costCenter Identifies the name of a cost center
organization Identifies the name of an organization
division Identifies the name of a division
department Identifies the name of a department

 

Response body

Example:

{
    "userName": "mariorossi@example.com",
    "name": {
        "formatted": "Mario Rossi",
        "familyName": "Rossi",
        "givenName": "Mario"
    },
    "displayName": "Mario Rossi",
    "preferredLanguage": "it-IT",
    "locale": "it-IT",
    "active": true,
    "emails": [
        {
            "value": "mariorossi@example.com",
            "type": "work",
            "primary": true
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "meta": {
        "resourceType": "User",
        "location": "https://your-subscription-hub-url/scim/users/b36e4fa2-2e6d-4acc-ad86-a01b7f79bdaa"
    },
    "id": "b36e4fa2-2e6d-4acc-ad86-a01b7f79bdaa",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {}
}

 

 

Differences from the SCIM standard

  • Include/exclude query parameters are not supported

 

 

 

Replace user

Use this call to replace user details.

 

Request

PUT  /Users
     Host: https://your-subscription-hub-url/scim
     Authorization: Bearer <id token here>
     Accept: application/scim+json
     Content-Type: application/scim+json

{
    "id": "c98b9447-1383-4bae-8133-f7c1bf8b3c96",
    "name": {
        "familyName": "Doe",
        "givenName": "John"
    },
    "locale": "it-IT",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ]
}

 

Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token
Accept: application/scim+json This call responds with a content type of application/scim+json
Content-Type: application/scim+json The response body is formatted as application/scim+json

 

User attributes

Same as those described in the Add a user call.

 

Response body

Example:

{
    "userName": "johndoe@example.com",
    "name": {
        "formatted": "John Doe",
        "familyName": "Doe",
        "givenName": "John"
    },
    "displayName": "John Doe",
    "preferredLanguage": "it-IT",
    "locale": "it-IT",
    "active": true,
    "emails": [
        {
            "value": "johndoe@example.it",
            "type": "work",
            "primary": true
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "meta": {
        "resourceType": "User",
        "location": "https://your-subscription-hub-url/scim/users/c98b9447-1383-4bae-8133-f7c1bf8b3c96"
    },
    "id": "c98b9447-1383-4bae-8133-f7c1bf8b3c96",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "Human Resources"
    }
}

 

Differences from the SCIM standard

  • Include/exclude query parameters are not supported

 

 

 

Edit user details

Use this call to request to edit user details. SCIM provides a rich patch specification based upon JSON Patch.

 

Request

PATCH /Users/{id}
      Host: https://your-subscription-hub-url/scim
      Authorization: Bearer <id token here>
      Accept: application/scim+json
      Content-Type: application/scim+json

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

 

Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token
Accept: application/scim+json This call responds with a content type of application/scim+json
Content-Type: application/scim+json The response body is formatted as application/scim+json

 

Operations

Each operation indicates how to act on the attribute. The only patch command supported for Users is replace.

Parameter Details
replace Whether to replace the attribute value

 

Path

The path indicates the attribute which is the target of the operation. In the Board implementation Path is always required.

Parameter Details

attribute

 The attribute to apply the operation to.
Example:externalId
attributePath[filter].subattribute
where filter is [attribute op value]		 The path signifies the target attribute to apply the operation to.
Example:name.givenName

 

Response body

Empty. 

 

 

 

Remove user

Use this endpoint to remove a single user.

 

Request

DELETE /Users/{id}
       Host: https://your-subscription-hub-url/scim
       Authorization: Bearer <id token here>

 

Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token

 

Curl example

curl -X DELETE -H 'Authorization: Bearer <id token here>'
https://your-subscription-hub-url/scim/Users/{id}

 

Response header

Header Details

Content-Type: application/scim+json

The response body is formatted as application/scim+json

 


Response body

Empty.

 

 

 

Get single Group details

Use this endpoint to retrieve all information of a single Group.

 

Request

GET /Groups/{id}
    Host: https://your-subscription-hub-url/scim
    Authorization: Bearer <id token here>

 

Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token

 

Curl example

curl -X GET -H 'Authorization: Bearer <id token here>'
https://your-subscription-hub-url/scim/Groups/{id}

 

Response header

Header Details

Content-Type: application/scim+json

The response body is formatted as application/scim+json

 


Response body

Example:

{
    "displayName": "Admins",
    "members": [
        {
            "value": "4da5e536-de8f-4eb3-acbb-c6933886ec3e",
            "$ref": "https://your-subscription-hub-url/scim/users/4da5e536-de8f-4eb3-acbb-c6933886ec3e",
            "type": "User",
            "display": "Eugen Russell"
        },
        {
            "value": "c98b9447-1383-4bae-8133-f7c1bf8b3c96",
            "$ref": "https://your-subscription-hub-url/scim/users/c98b9447-1383-4bae-8133-f7c1bf8b3c96",
            "type": "User",
            "display": "John Doe"
        },
        {
            "value": "f4b6c846-f0e6-407b-be03-fa6014c4e838",
            "$ref": "https://your-subscription-hub-url/scim/users/f4b6c846-f0e6-407b-be03-fa6014c4e838",
            "type": "User",
            "display": "Don Hale"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "meta": {
        "resourceType": "Group",
        "location": "https://your-subscription-hub-url/scim/groups/8b52ff11-3a03-41ad-55ab-08db35d9abed"
    },
    "id": "8b52ff11-3a03-41ad-55ab-08db35d9abed",
    "externalId": "222"
}

 

 

 

Get multiple Groups

Use this endpoint to search for Groups.

 

Request

Use a filter and provide the pagination parametersstartIndex and count to retrieve multiple users.

GET /Groups/?filter=displayName Eq "Admins"&startIndex=1&count=100
    Host: https://your-subscription-hub-url/scim
    Authorization: Bearer <id token here>

 

Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token

 

Request parameters

Pagination parameters

Parameter Details

startIndex

The pagination index to start with for the response

Default: 1
count

The pagination count per response

 

Filter parameters

Parameter Details

filter

A filter expression to restrict the result set in the form of <field> <operator> <value>

Example: displayName Eq “Admins”

Expressions may be separated with and, or or (  ) (not is not supported)

 

Filter fields

Field Details

id

Supported

externalId

Supported

displayName

Supported

 

Filter operators

Operators are case insensitive. E.g. Ne and ne both work.

The only operators supported are those in the table below.

Operator Details

Eq

- equal

- The attribute and operator values must be identical for a match

Ne

- not equal

- The attribute and operator values are not identical

Co

- contains

- The entire operator value must be a substring of the attribute value for a match

Sw

- starts with

- The entire operator value must be at the beginning of the attribute value. This criterion is satisfied if the two strings are identical

Ew

- ends with

- The entire operator value must be a substring of the attribute value, matching at the end of the attribute value. This criterion is satisfied if the two strings are identical

 

Complex Attributes

Complex attribute filtering, for instance searching in a complex array with the [ ] notation, is not supported.

 

Curl example

curl -X GET -H 'Authorization: Bearer <id token here>'
https://your-subscription-hub-url/scim/Groups?filter=externalId Eq "222"

 

Response header

Header Details

Content-Type: application/scim+json

The response body is formatted as application/scim+json

 

Response body

Example:

{
    "totalResults": 2,
    "itemsPerPage": 2,
    "startIndex": 1,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
        {
            "displayName": "Admins",
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "meta": {
                "resourceType": "Group",
                "location": "https://your-subscription-hub-url/scim/groups/9a405f2b-5b75-4ada-c5fc-08db345b5acf"
            },
            "id": "9a405f2b-5b75-4ada-c5fc-08db345b5acf",
            "externalId": "222"
        },
        {
            "displayName": "Planners",
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "meta": {
                "resourceType": "Group",
                "location": "https://your-subscription-hub-url/scim/groups/8b52ff11-3a03-41ad-55ab-08db35d9abed"
            },
            "id": "8b52ff11-3a03-41ad-55ab-08db35d9abed",
            "externalId": "111"
        }
    ]
}

 

 

Differences from the SCIM standard

  • Include/exclude query parameters are not supported
  • Supported filter query parameters, filter operators, filters fields: see tables above
  • Search is case-insensitive
  • Search with post ( /.search and /Groups/.search ) is not supported

 

 

 

Remove Group

Use this endpoint to remove a single Group.

 

Request

DELETE /Groups/{id}
       Host: https://your-subscription-hub-url/scim
       Authorization: Bearer <id token here>

 

Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token

 

Curl example

curl -X DELETE -H 'Authorization: Bearer <id token here>'
https://your-subscription-hub-url/scim/Groups/{id}

 

Response header

Header Details

Content-Type: application/scim+json

The response body is formatted as application/scim+json

 


Response body

Empty.

 

 

 

Add users to a Group

Use this call to add users to an existing Group.

 

Request

PATCH /Groups/{group-id}
      Host: https://your-subscription-hub-url/scim
      Authorization: Bearer <id token here>
      Accept: application/scim+json
      Content-Type: application/scim+json

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "add",
            "path": "members",
            "value": [
                {
                    "value": "{id}",
                    "type": "User"
                }
            ]
        }
    ]
}

 

Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token
Accept: application/scim+json This call responds with a content type of application/scim+json
Content-Type: application/scim+json The response body is formatted as application/scim+json

 

Operations

Each operation indicates how to act on the attribute. The operations are processed in the order received.

Parameter Details

add

 Whether to add the attribute value

 

Path

The path indicates the attribute which is the target of the operation. For this call, Path is always required and its value must always be members.

 

Response body

Empty.

 

 

 

Remove user from a Group

Use this call to remove users from a Group.

 

Request

PATCH /Groups/{group-id}
      Host: https://your-subscription-hub-url/scim
      Authorization: Bearer
      Accept: application/scim+json
      Content-Type: application/scim+json

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "remove",
            "path": "members",
            "value": [
                {
                    "value": "{id}"
                }
            ]
        }
    ]
}

 

Request headers

Header Details

Authorization: Bearer <id token here>

 In the Authorization header value, place the prefix Bearer followed by a space and then the ID Token
Accept: application/scim+json This call responds with a content type of application/scim+json
Content-Type: application/scim+json The response body is formatted as application/scim+json

 

Operations

Each operation indicates how to act on the attribute. The operations are processed in the order received.

Parameter Details
remove Whether to remove the attribute value

 

Path

The path indicates the attribute which is the target of the operation. For this call, Path is always required and its value must always be members.

 

Response body

Empty.

 

 

 

 

Error codes

Below are some of the error codes that you may encounter when using the Board SCIM APIs. If a call is only partially successful, an error message is returned to indicate what parts of the operation succeeded, and those that need your attention.

Example of an error response:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": 400,
    "detail": "No user found."
}

 

Error code details

When you call any of the REST operations, the response header returns one of the standard HTTP status codes described in the following table:

HTTP status code Description
200 (Ok) The request was successfully completed
201 (Created) The request has been fulfilled and resulted in a new resource being created
204 (No Content) When response body is empty.
For example, a DELETE request
400 (Bad Request) The request could not be processed because it contains missing or invalid information
404 (Not found) The request includes a resource URI that does not exist
405 (Method Unavailable) The HTTP verb specified in the request (DELETE, GET, POST, PUT) is not supported for this request
409 (Conflict) States conflict situation while executing the method. For example, adding a duplicate entry
500 (Internal Server Error) The server encountered an unexpected condition that prevented it from fulfilling the request
501 (Not Implemented) The requested operation is not supported by the service provider.
For example, a method not supported by the service provider, such as DELETE
503 (Service Unavailable) The server is unable to handle the request due to temporary overloading or maintenance of the server