SCIM API

V12 4:24 Ent.svg

 

Productboard SCIM API can be used used to provision, manage, and de-provision users (members).

The SCIM API is based on the Open standard: System for Cross-domain Identity Management 2. Our SCIM implementation uses the 2.0 version of the protocol.

In this article:

Relevant to both new and legacy boards

Implemented features

Our SCIM implementation supports Users (members in Productboard) and Groups (teams in Productboard).

With SCIM you can:

  • Get all users (members).
  • Update, activate, or deactivate users.
  • Get all Groups (teams).
  • Create, update and delete groups.
  • Add users to groups.

Unimplemented features

You can’t delete users (members). You can only deactivate them.

Supported identity providers

At the moment we support the following identity providers:

User (member) lifecycle with SCIM API

The user lifecycle starts when a company hires a new employee that will use Productboard and continues until the user leaves the company. Our SCIM API allows you to fully automate user management for Productboard. Let’s take a look at some common scenarios and what the ideal user experience in each should look like.

User onboarding

The first thing you usually need to do is to get the employee to Productboard. An identity provider (or your custom integration) should call the SCIM API to look up the user using filters, e.g:

https://api.productboard.com/scim/v2/Users&filter=userName eq "example@email.com"

. If the user exists already you can just update them if needed e.g. activate them or change their role. If the user doesn’t exist, the identity provider should call the create method. This method only requires the userName(Productboard email). If you don’t provide the role, the default role is contributor. Of course, you can provide other attributes. For the full list see User supported attributes.

User update

A user’s information and roles change over time and that has to reflect in permissions within company applications including Productboard.

The only attribute affecting permission in Productboard is role. For that, we use multivalued roles attribute. As a user you can have only one role in Productboard, therefore, we accept only

"primary": true, or the first role specified within roles attribute. Every other role is ignored.

Support articles mentioned in Supported identity providers cover thoroughly how to get roles working in your identity provider.

User offboarding

When a user leaves your company or no longer requires Productboard, you want to revoke their access. We don’t support user deletion, but you can deactivate their Productboard account by setting "active": false with an update request. 

Use your expertise in SCIM, or reach to your team's SCIM expert for more detail on how to complete these updates.

User supported attributes

SCIM protocol defines a lot of attributes, this is the subset of them we support:

Productboard attribute SCIM API attribute SCIM API namespace Description
Email userName urn:ietf:params:scim:schemas:core:2.0:User User email. Mandatory field.
Name displayName urn:ietf:params:scim:schemas:core:2.0:User Attribute is used if the value is not empty.
  name.formatted urn:ietf:params:scim:schemas:core:2.0:User Attribute is used if the displayName attribute is not provided, name attribute is provided and 'formatted' attribute value is not empty.
  name.givenName + " " + name.familyName urn:ietf:params:scim:schemas:core Attributes are used if the displayName attribute is not provided, name attribute is provided and formatted attribute is not provided.
  userName urn:ietf:params:scim:schemas:core:2.0:User Attribute will be used as Name if the displayName attribute is not provided and name attribute is not provided.
Activated active urn:ietf:params:scim:schemas:core:2.0:User Supported value: true or false
Role roles.^[primary==true].value (Okta)
roles[primary eq "True"].value (Microsoft Entra ID)
urn:ietf:params:scim:schemas:core:2.0:User Supported values are: admin, maker, contributor, viewer
Department department urn:ietf:params:scim:schemas:extension:enterprise:2.0:User  
Job title title urn:ietf:params:scim:schemas:core:2.0:User  
Id id urn:ietf:params:scim:schemas:core:2.0:User ID generated by Productboard.
SCIM External Id externalId urn:ietf:params:scim:schemas:core:2.0:User ID that we store when provided in a create or update request.

We only store the full name of users. For compatibility reasons, we use a combination of givenName and familyName if the displayName attribute is not present in a request. Also, in reponses we provide name.*attributes and emails attribute but they’re just parsed from Productboard Email and Name attributes.

User is handled in Productboard a bit differently than what’s possible to cover by SCIM API i.e. Productboard user with one email can have access to multiple workspaces. We don’t create a separate user for every workspace. The shared attributes are Name and Email, therefore when you change with update request any of them they’re updated “in every workspace”.

Group supported attributes

We support these group attributes:

Productboard attribute SCIM API attribute SCIM AP namespace Description
Name displayName urn:ietf:params:scim:schemas:core:2.0:Group Team name. Has to be unique.
ID id urn:ietf:params:scim:schemas:core:2.0:Group ID generated by Productboard.
Team members members urn:ietf:params:scim:schemas:core:2.0:Group Team members with their id and display name.

User supported methods

Get users

GET: https://api.productboard.com/scim/v2/Users

Retrieves the list of users in your workspace. Use startIndex and count

 query parameters to receive paginated results. The first item has

>startIndex = 1. This endpoint supports sorting and the filter parameter.

Sorting

Sorting allows you to specify the order in which resources are returned by specifying a combination of sortBy and sortOrder query parameters. The sortBy parameter specifies the attribute whose value will be used to order the returned responses. The sortOrder parameter defines the order in which the sortBy parameter is applied. Allowed values are ascending and descending. The default order (when sortOrder is not specified) is ascending.

Allowed attribute names for sortBy parameter are (case insensitive): id, externalId, userName, displayName, title, and active.

Example (sort users in descending order by their title):

GET: https://api.productboard.com/scim/v2/Users?sortBy=title&sortOrder=descending

Filters

You can request a subset of resources by specifying the filter query parameter containing a filter expression. Attribute names and attribute operators used in filters are case-insensitive. String attribute values are case insensitive as well, unless they have the caseExact attribute set to true in their schema. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and a value.

Allowed attribute operators are:

eq - equal

and - logical “and”

Allowed attribute names for filtering are (case insensitive): id,externalId, userName, displayName, title, and active.

Example (filter active users with display name set to foo:

GET: https://api.productboard.com/scim/v2/Users?filter=displayName eq "foo" and active eq true

Get user by id

GET: https://api.productboard.com/scim/v2/Users/848abbf8-1be7-4832-9f6b-140c00a9ca93

Retrieves a single user resource.

Create a new user

Creates a new user. Request payload has to include userName attribute.

POST: https://api.productboard.com/scim/v2/Users

Update user by id

Updates an existing user resource.

PUT: https://api.productboard.com/scim/v2/Users/848abbf8-1be7-4832-9f6b-140c00a9ca93

Update user attribute by id

PATCH: https://api.productboard.com/scim/v2/Users/848abbf8-1be7-4832-9f6b-140c00a9ca93

Updates an existing user resource. Only provided attributes are updated. Attributes that are not provided will remain unchanged. The payload of a request has to contain the attribute Operations.

Example payload:

{
	  "schemas": [
	    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
	  ],
	  "Operations": [
		  {
	      "op": "Add",
	      "path": "title",
	      "value": "Engineer"
		  }
	  ]
}

Group supported methods

Get groups

GET: <https://api.productboard.com/scim/v2/Groups>

Retrieves the list of groups in your workspace. Use startIndex and count query parameters to receive paginated results. The first item has startIndex = 1. This endpoint supports sorting and the filter parameter.

Filters

You can request a subset of resources by specifying the filter query parameter containing a filter expression. Attribute names and attribute operators used in filters are case-insensitive. String attribute values are case insensitive as well, unless they have the caseExact attribute set to true in their schema. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and a value.

Allowed attribute operators are:

eq - equal

and - logical “and”

Allowed attribute names for filtering are (case insensitive): iddisplayName.

Example (filter groups with display name set to foo:

GET: <https://api.productboard.com/scim/v2/Groups?filter=displayName> eq "foo"

Get group by id

GET: <https://api.productboard.com/scim/v2/Groups/ad8f91c2-8e6a-4845-80ed-fb42c1280fff>

Retrieves a single group resource.

Create a new group

Creates a new group.

POST: <https://api.productboard.com/scim/v2/Groups>

Update group by id

Updates an existing group resource.

PUT: <https://api.productboard.com/scim/v2/Groups/ad8f91c2-8e6a-4845-80ed-fb42c1280fff>

Update group attribute by id

PATCH: <https://api.productboard.com/scim/v2/Groups/ad8f91c2-8e6a-4845-80ed-fb42c1280fff>

Updates an existing group resource. Only provided attributes are updated. Attributes that are not provided will remain unchanged. The payload of a request has to contain the attribute Operations.

Example payload:

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "replace",
        "value": {
            "id": "ad8f91c2-8e6a-4845-80ed-fb42c1280fff",
            "displayName": "Test SCIMv2"
        }
    }]
}

Delete a group

Deletes an existing group resource.

DELETE: <https://api.productboard.com/scim/v2/Groups/ad8f91c2-8e6a-4845-80ed-fb42c1280fff>

Discovery methods

Schemas

GET: https://api.productboard.com/scim/v2/Schemas

Will return metadata about Users, Resource Types, Service Provider Config, extension attributes that are currently supported. You can just one schema by providing schema id e.g. 

GET:https://api.productboard.com/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig`.
Was this article helpful?
0 out of 1 found this helpful

Articles in this section

Our Support hours:
Monday to Friday from 9:00 am - 2:00 am CET. Monday to Friday from 0:00 am - 5:00 pm PST.
Productboard Academy
Become a Productboard expert with self-paced courses, quick tip videos, webinars and more.
Product Makers Community
Connect with product leaders, share and find product jobs, and learn how to approach similar challenges. Come join our Product Makers community.