Contents x
    SCIM API endpoints
    • 13 Jun 2024
    • 23 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    Contents

    SCIM API endpoints

    • Updated on 13 Jun 2024
    • 23 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    Article summary

    This section will cover the different calls, endpoints and errors possible with Boards SCIM API service. Read the SCIM API overview and Client API section for more information.

    Below are the SCIM calls and endpoints covered on this page:

    Other topics

    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

    {
    "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

    {
    "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.

    {
    "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

    {
    "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>

    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

    {
    "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

    addresses[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

    {
    "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

    {
    "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.externalId
    attributePath[filter].subattribute

    where filter is: [attribute op value]

    The path signifies the target attribute to apply the operation to.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

    {
    "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 parameters startIndex 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>

    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

    {
    "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

    Was this article helpful?
    What's Next