Routes

List and Search

Parameters

Get a single User, Workspace, or Board

User

GET /scim/v2/Users/USER_ID - e.g. /scim/v2/Users/58d11883e7ea028acc5b19a4

Group (Workspaces and Boards)

GET /scim/v2/Groups/GROUP_ID

Create a new User

POST /scim/v2/Users sending a header of Content-type: application/json and a body with a User resource representation, such as: {"displayName": "David Walliams", "emails": [ { "value": "dw@example.com" } ] }

The following attributes will be used; any other will be ignored:

• Required:
  • one of displayName, name.formatted, or name.givenName and name.familyName
  • emails.value
• Optional:
  • userName - Normally best to omit, and one will be auto-generated. If supplied, must be 3-100 characters of only lowercase letters, underscores and numbers.
  • locale
  • timezone

If successful, the response will have a status of 201, and contain the full User resource in the body. The user will be enabled for Single Sign On if the enterprise has this configured. Otherwise, the user will need to reset their password to set a password for login.

The created Trello user will be owned by the enterprise. If the enterprise has domains configured, the user will not email address require confirmation. Otherwise, an email will be sent asking the user to confirm their address.

At present, it is not possible to assign a user to any Workspaces or Boards at creation. This may be supported in a later release of the Trello SCIM API.

Update a User

Currently, you can only update a user's active attribute. We plan to support updating other attributes at some point in the future.

When a user is set to active: false, they will be deactivated from all enterprise Workspaces and boards. If the user is then set to active: true, they will be reactivated on any Workspaces and boards they had previously been deactivated from when deactivated from the enterprise (via the SCIM API or Enterprise Admin Dashboard).

If the user had been deactivated from each Workspaces individually, setting them to active: true via the SCIM API will reactivate them in all the enterprise Workspaces they were previously a member of.

A user can be updated via PATCH or PUT requests. Remember to send a Content-type header with application/json or application/scim+json.

Updating active via PATCH

PATCH https://trello.com/scim/v2/Users/58d11883e7ea028acc5b19a4

1
2
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]
  "Operations": [ { "op": "replace", "value": { "active": false } } ]
}

Updating via PUT

PUT https://trello.com/scim/v2/Users/58d11883e7ea028acc5b19a4

1
2
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "https://trello.com/scim/v2/schemas/TrelloUser"
  ],
  "displayName": "Little Bobby Tables",
  "name": { "formatted": "Little Bobby Tables" },
  "userName": "bobby_tables",
  "active": false,
  "emails": [
    {
      "value": "bobby_tables@example.com",
      "primary": true
    }
  ]
}

Whilst at present everything other than the active attribute is ignored, in future we may support updating other attributes via PUT.

Therefore you should GET the current state of the User, modify the active attribute, and PUT the whole user representation, to avoid unintentionally changing other attributes.

Schemas

GET /scim/v2/Schemas

Gives details of all the attributes used in each resource type.

ResourceTypes

GET /scim/v2/ResourceTypes

Gives details about each resource type available.

ServiceProviderConfig

GET /scim/v2/ServiceProviderConfig

Gives details about the features available in the SCIM API.

Filtering

Resources can be filtered using powerful yet simple query expressions. This is sent in the filter parameter of a GET request. An example of a basic filter expression is: userName eq "matt" i.e. in the form {attribute} {operator} {comparison value}

Attributes

Pretty much any of the attributes you see in resource responses can be used. Use a dot syntax for subattributes, e.g. emails.value

Operators

Comparison Values

This can be:

• a string, enclosed in "double quotes",
• a number, e.g. 5
• a date or date-time, in ISO 8601 format, enclosed in double quotes: e.g. "2017-01-01"
• Boolean true or false

Combining Expressions

Expressions can be combined with AND and OR. e.g.: userName sw "m" OR emails.value co "@atlassian.com"

You can also use parentheses for grouping: (userName co "bob" and active eq true) or displayName ew "Smith"

NOT

You can use NOT to invert an expression: name.formatted co "bob" AND NOT name.formatted co "holness"

Multi-value attributes

S CIM resources can have multi-value attributes (AKA arrays). For example, a User's emails might look like this:

1
2
{
  ...,
  "emails": [
    { "value": "frank.underwood@gmail.com", primary: false },
    { "value": "potus@whitehouse.gov", primary: true }
  ]
}

Say you wanted to find Users who have a Gmail address as their primary email address (a set that this example user is not part of).

If you filtered for: emails.value ew "@gmail.com" and emails.primary eq true

then our example user would match, because he has an email ending with @gmail.com and a primary email. Even though they are different emails.

To find only those Users who have a Gmail address that is primary, use a filter like this: emails[value eq "@gmail.com" and primary eq true]

That will only match Users where one emails matches both conditions. If the equivalent of MongoDB's elemMatch, if you're familiar with that.