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:
- Implemented features
- Not implemented features
- Supported identity providers
- User (member) lifecycle with SCIM API
- User supported attributes
- User supported methods
- Group supported methods
- Discovery methods
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:
- Microsoft Entra ID - Setting up SCIM provisioning with Microsoft Entra ID
- Okta - Setting up SCIM provisioning with OKTA
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 |
---|---|---|---|
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): id, displayName.
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`.