Named User Service SCIM API – uStudio

Named User Service allows you to implement SCIM protocols with uStudio. You can perform create, read, update, and delete (CRUD) operations on users and groups. In addition, you can apply filters to your queries on users and create custom schemas. These actions give you more flexibility in controlling your user base in real time.

We use tokens to authenticate every connection. The service account that will be running the CRUD operations will authenticate with its API token. While each user will authenticate with a short lived token. This token is reissued if and only if the user has valid access. Otherwise, when the user is deactivated, the short lived token will expire and the user will no longer be able to connect to uStudio.

Prerequisites

Please contact support@ustudio.com to establish a service account and to receive your SCIM API TOKEN, ACCOUNT-UID, and CONNECTION-UID.

Base Route

API requests will require a Named User Service Token as a Bearer TOKEN in the Authorization Header.

Base URL

https://named-users.ustudio.com/api/v1/accounts/ACCOUNT-UID/connections/CONNECTION-UID

User Routes

These routes should allow standard SCIM clients to perform create, read, update, and delete (CRUD) operations on users in uStudio. Example of a user entry:

{
  "userName": "flastname@domain.com",
  "name": {
    "givenName": "Firstname",
    "familyName": "Lastname"
  },
  "active": true,
  "emails": [{
    "value": "flastname@domain.com",
    "primary": true
  }],
  "externalId": null
}

List all users

GET {{BASE-URL}}/Users

Create new user

POST {{BASE-URL}}/Users

Get user details

GET {{BASE-URL}}/Users/USER-UID

Update user details

PUT {{BASE-URL}}/Users/USER-UID

Group Routes

These routes should allow clients to do actions on a Named Users Service Group. Each group entry may contain the following fields:

{
  "displayName": "NAME",
  "externalId": "EXTERNAL-IDENTIFIER",
  "members": [{
    "value": "USER-UID"
  }],
  "urn:scim:ustudio:internal": {
    "description": "DESCRIPTION"
  }
}

Get Groups

GET {{BASE-URL}}/Groups

Create Group

POST {{BASE-URL}}/Groups

Get Group Details

GET {{BASE-URL}}/Groups/GROUP-UID

Update Group

PUT {{BASE-URL}}/Groups/GROUP-UID

Update Group with PATCH

PATCH {{BASE-URL}}/Groups/GROUP-UID

# Example
{
  "schemas":
    ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "displayName",
        "value": "PATCHED-NAME"
      },
      {
        "op": "add",
        "path": "members",
        "value": [{
          "value": "USER-UID"
        }]
      },
      {
        "op": "remove",
        "path": "members[value eq \"USER-UID\"]"
      },
      {
        # this will remove all members in the group
        "op": "remove",
        "path": "members"
      },
    ]
}

Delete Group

DELETE {{BASE-URL}}/Groups/GROUP-UID

Filtering

For methods that return a list --- GET /Users --- it's possible to filter the list by the userName, emails, active, name.givenName, and name.familyName attributes, and return only the values matching that filter. The following rules apply:

The filter parameter must contain one valid boolean operator.
Each expression must contain an attribute name followed by an attribute operator, (also supports an optional value).
Multiple expressions may be combined using two logical operators.
Expressions can be grouped together using "( )".
Expressions must be evaluated using standard order of operations.
String literals must be valid JSON strings.

The following is a list of valid operators:

Operator	Description
eq	equal
co	contains
sw	starts with
pr	present value
gt	greater than
ge	greater than or equal
lt	less than
le	less than or equal
and	logical And
or	logical Or

Attribute name and attribute operator are case insensitive. For example, the following two expressions will evaluate to the same logical value:

filter=userName Eq "Carly"
filter=username eq "carly"

Custom Schemas

Custom schemas are used to update or view extra fields pertaining to an object that is not part of the core schema.

# PATCH example 
# https://named-users.studionodes.net/api/v1/accounts/ACCOUNT/groups/GROUP-UID 
{ 
  "schemas": [ 
    "urn:ietf:params:scim:api:messages:2.0:PatchOp", 
    "urn:ietf:params:scim:schemas:extension:ustudio.com:2.0:Group" 
  ], 
  "Operations": [ 
    { 
      "op": "replace", 
      "value": { 
        "urn:ietf:params:scim:schemas:extension:ustudio.com:2.0:Group": { 
          "description": "DESCRIPTION" 
        } 
      } 
    } 
  ] 
} 

# PUT example 
# https://named-users.studionodes.net/api/v1/accounts/ACCOUNT/groups/GROUP-UID 
{ 
  "schemas": [ 
    "urn:ietf:params:scim:api:messages:2.0:PatchOp", 
    "urn:ietf:params:scim:schemas:extension:ustudio.com:2.0:Group" 
  ], 
  "urn:ietf:params:scim:schemas:extension:ustudio.com:2.0:Group": { 
    "description": "DESCRIPTION" 
  } 
}

uStudio custom schemas:

urn:ietf:params:scim:schemas:extension:ustudio.com:2.0:Group
urn:ietf:params:scim:schemas:extension:ustudio.com:2.0:User