The Shorthand SCIM API is currently in Beta and only available on specific plans — please contact us for details.

SCIM, or System for Cross-domain Identity Management, is an open standard for automating user provisioning. Shorthand's SCIM API implementation targets version 2.0 of the SCIM protocol.

The owner of a Shorthand workspace can request that the SCIM API feature be enabled to allow the provisioning and managing of user accounts with the Shorthand SCIM API, including:

Create, edit or delete a member
Create, edit or delete a team
Add or remove members from a team
Assign user roles in a team

The formal SCIM specification is provided by the following two documents:

SCIM: Core Schema (RFC 7643)
SCIM: Protocol (RFC 7644)

Security

The Shorthand SCIM API requires TLS1.2 support, so please ensure that your client code supports this protocol.

Accessing the SCIM API

Only the owner of the workspace may generate a SCIM API token and authentication is carried out at a workspace level, managing users across the entire workspace.

If you are the owner of the workspace, and provisioning has been enabled for that workspace, the components required to configure your SCIM API integration may be found in the workspace settings.

First, click your circular account avatar at the top left corner anywhere in the Shorthand app. Next, select "API Tokens", beneath the "Workspace settings" heading.

Under "Provisioning", click the "GENERATE" button to create a token if none exists; store this value securely as it provides access to your Shorthand workspace. An existing token may be invalidated by clicking the "REGENERATE" button.

Click the "COPY SCIM ENDPOINT URL" button to copy the location you will use to connect to the SCIM API.

Use the token in a SCIM API request

The provisioning token is a bearer tokens that must be added as an Authorization header when requesting SCIM endpoints, with the value, Bearer <token>.

As per the SCIM specification, all SCIM requests should be made with a Content-Type header of application/scim+json.

Endpoints

The following routes comprise the Shorthand SCIM API. Each should be prefixed with the endpoint URL location copied via the button in Workspace Settings. For example, /ServiceProviderConfig might be accessed from an endpoint similar to https://api.shorthand.com/scim/<Provisioner ID>/v2/ServiceProviderConfig.

Endpoint	Description
`GET /ServiceProviderConfig`	Returns configuration details for the Shorthand SCIM API, including which operations are supported
`GET /ResourceTypes`	Returns all types of resources available in the Shorthand SCIM API, such as `User` and `Team`, the endpoints where they are exposed, and the schemas that define them
`GET /ResourceTypes/{type}`	Returns the description of a single type of resource specified by the resource type {type}, such as `User` or `Team`
`GET /Schemas`	Returns the schema documents for all non-standard schemas associated with the API
`GET /Schemas/{schema-urn}`	Returns a schema document for the given schema URN {schema-urn}
`GET /Users`	Returns a paginated list of users in the workspace
`GET /Users/{id}`	Returns a single user who matches the {id} provided
`POST /Users`	Creates a user
`PATCH /Users/{id}`	Patches an existing user who matches the {id}, updating according to the patch operations in the request body (See RFC7644, 3.5.2)
`PUT /Users/{id}`	Updates an existing user who matches the {id}, overwriting all values
`DELETE /Users/{id}`	Soft deletes a Shorthand user matching the {id} and removes the user from the workspace
`GET /Groups`	Not applicable as Shorthand does not use groups in the SCIM definition
`GET /Teams`	Returns a paginated list of teams in the workspace
`GET /Teams/{id}`	Returns a single team who matches the {id} provided
`POST /Teams`	Creates a new team
`PATCH /Teams/{id}`	Patches an existing team who matches the {id}, updating according to the patch operations in the request body (See RFC7644, 3.5.2)
`DELETE /Teams/{id}`	Permanently removes a team matching the {id}, if there are no stories or members within that team

SCIM API implementations are intended to be self-documenting. The /ResourceTypes endpoint in conjunction with the /Schemas endpoint describes the types of resources and their representations.

Example Attributes

Create a new user:

POST /Users{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "externalId": "ExternalID01",
  "userName": "[email protected]",
  "name": {
    "givenName": "Bob",
    "familyName": "Builder"
  },
  "active": true
}

Change the name of the user:

PATCH /Users/{id}{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{
    "op": "replace",
    "value": {
      "name": {
        "givenName": "John",
        "familyName": "Doe"
      }
    }
  }]
}

Create a new team with a single member:

POST /Teams{
  "schemas": ["urn:ietf:params:scim:schemas:Shorthand:2.0:Team"],
  "externalId": "Team4",
  "displayName": "Team4",
  "members": [{
     "value": "a-user-id",
     "role": "member"
  }]
}

Rename the team and add a second team member:

PATCH /Teams/{id}{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{
    "op": "replace",
    "path": "displayName",
    "value": "Team name 4 - has member"
  }, {
    "op": "add",
    "path": "members",
    "value": {
      "value": "user-id-2",
      "role": "member"
    }
  }]
}

Promote a member of a team to a team leader and rename the team:

PATCH /Teams/{id}{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{
    "op": "replace",
    "path": "members[value eq \"user-id-2\"]",
    "value": {
      "value": "user-id-2",
      "role": "leader"
    }
  }, {
    "op": "replace",
    "value": { "displayName": "Team name 4 - has leader" }
  }]
}

Managing your team(s) with the Shorthand SCIM API (Beta)