API docs by Redocly

Stensul API (1.0.0)

Download OpenAPI specification:

Download Postman Collection: Download

This API uses OAuth 2.0 for authentication and adheres to the SCIM (System for Cross-domain Identity Management) protocol for user management.

Documentation Structure

This documentation is organized into the following structure:

Rate limiting

Our API implements rate limiting to ensure fair usage and prevent abuse. Specifically, we limit requests to 30 per second per IP address. This helps us maintain the stability and performance of our API by preventing any single IP address from overwhelming our servers with too many requests. Rate limiting also encourages responsible use of our API and helps protect it from potential malicious attacks.

Additional Notes

{baseUrl} represents the URL of your Stensul instance, for example https://mycompany.stensul.com

Authentication

OAuth Authentication

Get access token

Using OAuth 2.0 client credentials grant type request an access token to use the External API. This access token must be passed as a Bearer token.

If you don't request explicit scopes, the default one will be assigned (api-read).

Default token expiration: 6 hours (expressed in seconds)

Authorizations:
bearerAuth
Request Body schema: application/json
grant_type
required
string
client_id
required
string <uuid>
client_secret
required
string
scope
Array of strings
Items Enum: "api-read" "api-write"

Responses

Request samples

Content type
application/json
Example
{
  • "grant_type": "client_credentials",
  • "client_id": "1bdf2ba9-a5fa-42c5-81d3-beae2629e469",
  • "client_secret": "aiQldD3IqJ2p9004ba8zNYDyxFxpjqq334fxu8e1",
  • "scope": [
    ]
}

Response samples

Content type
application/json
{
  • "token_type": "Bearer",
  • "expires_in": 21600,
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5YmRmMmJhOS1hNWZhLTQyYzUtODFkMy1iZWFlMjYyOWU0NjkiLCJqdGkiOiI5NDBlNGNkMTZhYzU5ZWE0YzBhODA3MWIxMzU4MmRmYjUwY2IwMzA4MzUwMTIzNGVmY2ExNzQ4YjZlN2Y0ODc5OWNjNzczZWViMjU5YTgzNiIsImlhdCI6MTcxNDE0MDUwNi4yODQ2Nzg5LCJuYmYiOjE3MTQxNDA1MDYuMjg0Njg4OSwiZXhwIjoxNzE0MTYyMTA2LjI3MDgzNzEsInN1YiI6IiIsInNjb3BlcyI6WyJhcGktcmVhZCIsImFwaS13cml0ZSJdfQ.tPvGbxd_pWnWpXyOMGNBzn_ufjMROD31u3YTry51jZa31s3uT6ladAxtDvtY1MaqqnHbkV9P1W6krYL-3Q4WZt1Y52jfi_eNMh82Q31RaZSnmtJ_R65mWjcJmxH1hoZkHYT15sBFq-9osPSN2Vh-EqkbYz6tUCqZRPOSz97w5D8fNC2zldrLTu-O-7-qUpdFGccY2BjW8CNAuKK_nCc500wKe6US-HIE_fjSTW0HHZqRp7I4dNWT01kgMX-NJ3DHZP0irAfKWQrU7u5G-V5we7hs8Ke3ZwC0-6QCo9MucZwsICIkFKzj7PFNE2qeJHERZA-nc1-L_cV7_DvameWwIm6NcDgrsNLuXfupQw9riWBZmsv7-9RmgwKZ4r4SRhpSIB35wbAUgV9kX2ZcpX-thfZoATjVMoWUsB-m7YOpYxzpnpQSjk8ZLvK6_NX0dCVywfbbsQlZubQNKNd1wqJRBWS29z-elnu3G58fxVSEdjfbLvVxcrQrYObRNWvhgSKZcL-KgcLOTQnU_XEkNw1FRHi6HvehKLRs56UpL-uZmPkrTWBBJUDZ6gUNZiK372Owa9-p7QH4OJ1IDWuUAq4opPBxLZEMg0Gj04V0dwnIBYHKRcgzRAdsqVfzkYcE8y9DbmyxoPvkCzvK0hj_l9rtBAIczJCkhVvKpibQ3JQf9ow"
}

Libraries

Manage Stensul Libraries

Get Libraries

GET /api/v1/libraries

This endpoint retrieves a list of libraries with the option to sort, filter and paginate the results.

Request Body

No request body parameters are required for this endpoint.

Response Body

The response returns a JSON object with the following schema:

{
    "data": [
        {
            "attributes": {
                "id": "string",
                "name": "string",
                "key": "string",
                "description": "string",
                "permission": "string",
                "created_at": "string",
                "updated_at": "string",
                "created_by": "string",
                "updated_by": "string",
                "tags": [
                    "string"
                ]
            }
        }
    ],
    "links": {
        "first": "string",
        "last": "string",
        "prev": null,
        "next": "string"
    },
    "meta": {
        "current_page": integer,
        "from": integer,
        "last_page": integer,
        "links": [
            {
                "url": "string",
                "label": "string",
                "active": boolean
            }
        ],
        "path": "string",
        "per_page": integer,
        "to": integer,
        "total": integer
    }
}

The response includes an array of library objects with attributes such as ID, name, key, description, permission, creation and update timestamps, as well as creator and updater details. The response also includes links for pagination and meta information about the current page and total count.

Authorizations:
bearerAuth
query Parameters
filter[name]
string
Example: filter[name]=My Library

Allow filtering resource results by name.

sort
string
Example: sort=name

Allow sorting resource results. Provide a - (minus) before criteria for descending order. Allow comma-separated values.

Available values : name, created_at, updated_at

page[size]
integer
Example: page[size]=15

For paginated responses indicates the amount of resource results to be retrieved per page.

Maximum resources: 30. Default is 15.

page[number]
integer
Example: page[number]=1

For paginated responses indicates the page number to be retrieved.

header Parameters
Content-Type
string
Example: application/json
Accept
string
Example: application/json

Responses

Response samples

Content type
application/json
{}

Get a Library

GET /api/v1/libraries/{{libraryId}}

This endpoint retrieves Library information based on the provided Library ID.

Request Body

No request body parameters are required for this endpoint.

Response Body

The response returns a JSON object with the following schema:

{
    "data": {
        "attributes": {
            "id": "string",
            "name": "string",
            "key": "string",
            "description": "string",
            "permission": "string",
            "created_at": "string",
            "updated_at": "string",
            "created_by": "string",
            "updated_by": "string",
            "modules": [
                {
                    "moduleId": "string",
                    "name": "string"
                },
            ],
            "tags": [
                "string"
            ],
            "config": {
                "templateWidth": integer,
                "templateMobileWidth": integer,
                "templateMobileBreakpoint": integer,
                "enableMobile": boolean,
                "templateBackgroundColor": "string",
                "contentBackgroundColor": "string",
                "templateBackgroundPalettes": "string",
                "colorPalettes": "string",
                "fontFamily": "string",
                "fontSize": integer,
                "fontColor": "string",
                "lineHeight": integer,
                "linkColor": "string",
                "linkDecoration": "string",
                "propietaryCss": "string",
                "externalCssLink": "string",
                "personalizationTags": [],
                "insertBody": boolean,
                "prependHtml": "string",
                "appendHtml": "string",
                "padding": "string",
                "isTitleEnabled": boolean,
                "titleDefault": "string",
                "htmlCustomHead": "string",
                "esp": boolean,
                "espProvider": [],
                "emailTestSending": boolean,
                "emailTestSendingIntegrationKey": "string",
                "emailTestSendingUseMinifiedOutput": boolean,
                "dynamicAuthoring": boolean,
                "dynamicAuthoringProvider": "string",
                "dynamicAuthoringType": "string",
                "languageEnabled": boolean,
                "languages": [
                    "string"
                ],
                "defaultLanguage": "string",
                "workflow": boolean,
                "workflowProvider": [],
                "messaging": boolean,
                "messagingProvider": [],
                "outputFormats": boolean,
                "outputFormatsValues": [
                    "string"
                ],
                "htmlToPdf": boolean,
                "pdfSettings": [],
                "htmlToOft": boolean,
                "htmlToEmltpl": boolean,
                "plainText": boolean,
                "maskLink": boolean,
                "preheader": boolean,
                "preheaderDefault": "string",
                "preheaderRequired": boolean,
                "preheaderMaxLengthEnabled": boolean,
                "preheaderMaxLength": integer,
                "isSubjectLineEnabled": boolean,
                "subjectLineMaxLengthEnabled": boolean,
                "subjectLineMaxLength": integer,
                "subjectLineAbTestEnabled": boolean,
                "tracking": boolean,
                "trackingConfig": "",
                "urlTracking": boolean,
                "urlTrackingParameters": {
                    "allowUserToDeactivate": boolean,
                    "campaign": [],
                    "element": []
                },
                "urlTrackingRequired": boolean,
                "urlTrackingOption": "string",
                "customizationRequestsEnabled": boolean,
                "customizationRequestsRecipients": [],
                "variations": {
                    "default": "string",
                    "mode": "string"
                },
                "require_approvals": boolean,
                "minify_output_by_default": boolean,
                "fixedModules": {
                    "header": {
                        "moduleId": "string",
                        "name": "string"
                    },
                    "footer": {
                        "moduleId": "string",
                        "name": "string."
                    },
                },
                "skip_complete_modal": boolean,
                "defaultView": "string"
            }
        }
    }
}
Authorizations:
bearerAuth
path Parameters
libraryId
required
string
header Parameters
Content-Type
string
Example: application/json
Accept
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Emails

Manage Stensul Emails

Create an Email

POST /api/v1/emails

This endpoint creates an email.

Request Body

  • library_key (text, required) - The library key. Can be obtained with the endpoint /api/v1/libraries endpoint.

  • name (text, required) - The email name.

  • type (text, optional) - The type of email, valid values include "draft" and "template". Default: "draft".

  • title (text, optional) - The title of the email. If not used, the Library default will be used (if set).

  • tags (array, optional) - The email tags. Tags must be available to the Library.

  • preheader (text, optional) - The preheader of the email. If not used, the Library default will be used (if set).

  • subject_line (text, optional) - The subject line of the email. If not used, the Library default will be used (if set).

  • language (text, optional) - The email language. It must be one of the selected values on the library. If not used, the Library default will be used.

Response Body

The response returns a JSON object with the following schema:

{
    "data": {
        "id": "string",
        "name": "string",
        "type": "string",
        "tags": array,
        "is_archived": boolean,
        "has_modules_locked": boolean,
        "has_been_uploaded": boolean,
        "downloadable_as": array,
        "is_exportable_to_esp": boolean,
        "is_translatable": boolean,
        "has_active_proof": boolean,
        "has_autosave_enabled": boolean,
        "library_id": "string",
        "library_name": "string",
        "library_key": "string",
        "has_outdated_modules": boolean,
        "preview_image_url": "string",
        "thumbnail_url": "string",
        "preheader": "string",
        "subject_line": "string",
        "title": "string",
        "tracking": {
            "param1": "string",
            "param2": "string",
        },
        "personalization_tags": array,
        "language": "string",
        "has_translation_process_started": null,
        "created_at": "string",
        "updated_at": "string",
        "created_by": {
            "id": {
                "$oid": "string"
            },
            "email": "string",
            "fullname": "string"
        },
        "updated_by": {
            "id": {
                "$oid": "string"
            },
            "email": "string",
            "fullname": "string"
        },
        "modules_locked_by": null,
        "last_proof": {
            "id": "string",
            "status": "string"
        },
        "original_language_campaign_id": "string",
        "schedule": {
            "status": "string",
            "date": "string",
            "sent_at": "string",
            "audiences": [
                "string"
            ],
            "is_scheduled": boolean,
            "is_sent": boolean,
            "created_at": "string",
            "updated_at": "string"
        },
        "outputs": [
            {
                "format": "string",
                "content": "string",
                "content_minified": "string"
            }
        ]
    }
}
Authorizations:
bearerAuth
header Parameters
Content-Type
string
Example: application/json
Accept
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "library_key": "my_library",
  • "name": "Test Email",
  • "type": "draft",
  • "title": "The Email Title",
  • "tags": [
    ],
  • "preheader": "The Email Preheader",
  • "subject_line": "The Subject Line",
  • "language": "en-US"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Emails

GET /api/v1/emails

This endpoint retrieves a list of emails with the option to sort, filter and paginate the results.

Request Body

No request body parameters are required for this endpoint.

Response Body

The response returns a JSON object with the following schema:

{
    "data": [
        {
            "id": "string",
            "name": "string",
            "type": "string",
            "tags": array,
            "is_archived": boolean,
            "has_modules_locked": boolean,
            "has_been_uploaded": boolean,
            "downloadable_as": array,
            "is_exportable_to_esp": boolean,
            "is_translatable": boolean,
            "has_active_proof": boolean,
            "has_autosave_enabled": boolean,
            "library_id": "string",
            "library_name": "string",
            "library_key": "string",
            "has_outdated_modules": boolean,
            "preview_image_url": "string",
            "thumbnail_url": "string",
            "preheader": "string",
            "subject_line": "string",
            "title": "string",
            "tracking": {
                "param1": "string",
                "param2": "string",
            },
            "personalization_tags": array,
            "language": "string",
            "has_translation_process_started": null,
            "created_at": "string",
            "updated_at": "string",
            "created_by": {
                "id": {
                    "$oid": "string"
                },
                "email": "string",
                "fullname": "string"
            },
            "updated_by": {
                "id": {
                    "$oid": "string"
                },
                "email": "string",
                "fullname": "string"
            },
            "modules_locked_by": null,
            "last_proof": {
                "id": "string",
                "status": "string"
            },
            "original_language_campaign_id": "string",
            "schedule": {
                "status": "string",
                "date": "string",
                "sent_at": "string",
                "audiences": [
                    "string"
                ],
                "is_scheduled": boolean,
                "is_sent": boolean,
                "created_at": "string",
                "updated_at": "string"
            },
            "outputs": [
                {
                    "format": "string",
                    "content": "string",
                    "content_minified": "string"
                }
            ]
        }
    ],
    "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
    },
    "meta": {
        "current_page": integer,
        "from": integer,
        "last_page": integer,
        "links": [
            {
                "url": "string",
                "label": "string",
                "active": boolean
            }
        ],
        "path": "string",
        "per_page": integer,
        "to": integer,
        "total": integer
    }
}

The response includes an array of email objects with attributes such as ID, name, library_id, creation and update timestamps, as well as creator and updater details. The response also includes links for pagination and meta information about the current page and total count.

Authorizations:
bearerAuth
query Parameters
sort
string
Example: sort=-created_at

Allow sorting resource results. Provide a - (minus) before criteria for descending order. Allow comma-separated values.

Available values: name, type, created_at, updated_at

page[number]
integer
Example: page[number]=1

For paginated responses indicates the page number to be retrieved.

page[size]
integer
Example: page[size]=20

For paginated responses indicates the amount of resource results to be retrieved per page.

Maximum resources: 30. Default is 15.

filter[name]
string

Allow filtering resource results by name.

filter[types][]
string
Example: filter[types][]=draft

Allow filtering resource results by type, available types are "draft", "finished" or "template". This filter can be added more than once to include results with different types.'

filter[library_keys][]
string
Example: filter[library_keys][]=library_1

Allow filtering results by Library Key. This filter can be added more than once to include results with different libraries.

filter[tags][]
string
Example: filter[tags][]=translation,es

Allow filtering by tags. This filter can be added more than once to include results with different tags.

filter[language]
string
Example: filter[language]=en-US

Allow filtering by language code as defined by ISO 639-1 including additional language tags representing regional subtypes defined in IETF's BCP 47.

filter[has_modules_locked]
integer

Filter emails by whether their modules have been locked or not. Valid values are 0 or 1.

By default all emails will be returned.

filter[has_been_uploaded]
integer
Example: filter[has_been_uploaded]=1

Allow filtering for emails uploaded to an ESP. Valid values are 0 or 1.

By default all emails will be returned.

filter[is_archived]
integer
Example: filter[is_archived]=1

Allow filtering for archived emails. Valid values are 0 or 1.

By default all emails will be returned.

q
string
Example: q=My search terms

Allows searching for emails by Email Name, Author, Tags and Library name.

fields
string
Example: fields=name,type,tags,created_by,library_name

Specify fields to return in the response, multiple fields can be separated with commas.

Every email attribute will be returned if this parameter is not used.

Valid fields are: id, name, type, tags, is_archived, has_modules_locked, has_been_uploaded, downloadable_as, is_exportable_to_esp, is_translatable, has_active_proof, has_autosave_enabled, library_id, library_name, library_key, has_outdated_modules, preview_image_url, thumbnail_url, preheader, subject_line, tracking, personalization_tags, language, has_translation_process_started, created_at, updated_at, created_by, updated_by, modules_locked_by, original_language_campaign_id, schedule, outputs.

header Parameters
Content-Type
string
Example: application/json
Accept
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {}
}

Get an Email

GET /api/v1/emails/{{emailId}}

This endpoint retrieves email information based on the provided email ID.

Request Body

No request body parameters are required for this endpoint.

Response Body

The response returns a JSON object with the following schema:

{
    "data": {
        "id": "string",
        "name": "string",
        "type": "string",
        "tags": array,
        "is_archived": boolean,
        "has_modules_locked": boolean,
        "has_been_uploaded": boolean,
        "downloadable_as": array,
        "is_exportable_to_esp": boolean,
        "is_translatable": boolean,
        "has_active_proof": boolean,
        "has_autosave_enabled": boolean,
        "library_id": "string",
        "library_name": "string",
        "library_key": "string",
        "has_outdated_modules": boolean,
        "preview_image_url": "string",
        "thumbnail_url": "string",
        "preheader": "string",
        "subject_line": "string",
        "title": "string"
        "tracking": {
            "param1": "string",
            "param2": "string",
        },
        "personalization_tags": array,
        "language": "string",
        "has_translation_process_started": null,
        "created_at": "string",
        "updated_at": "string",
        "created_by": {
            "id": {
                "$oid": "string"
            },
            "email": "string",
            "fullname": "string"
        },
        "updated_by": {
            "id": {
                "$oid": "string"
            },
            "email": "string",
            "fullname": "string"
        },
        "modules_locked_by": null,
        "last_proof": {
            "id": "string",
            "status": "string"
        },
        "original_language_campaign_id": "string",
        "schedule": {
            "status": "string",
            "date": "string",
            "sent_at": "string",
            "audiences": [
                "string"
            ],
            "is_scheduled": boolean,
            "is_sent": boolean,
            "created_at": "string",
            "updated_at": "string"
        },
        "outputs": [
            {
                "format": "string",
                "content": "string",
                "content_minified": "string"
            }
        ]
    }
}
Authorizations:
bearerAuth
path Parameters
emailId
required
string
header Parameters
Content-Type
string
Example: application/json
Accept
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

SCIM - User Provisioning

Manage Stensul Users

Get a user resource

GET /scim/v2/Users/{userId}

This endpoint retrieves user information based on the provided user ID.

Request Body

No request body parameters are required for this endpoint.

Response Body

The response returns a JSON object with the following schema:

{
    "id": "string",
    "externalId": "string",
    "meta": {
        "created": "string",
        "lastModified": "string",
        "location": "string",
        "resourceType": "string"
    },
    "urn:ietf:params:scim:schemas:core:2.0:User": {
        "userName": "string",
        "name": {
            "formatted": "string",
            "familyName": "string",
            "givenName": "string"
        },
        "active": true,
        "groups": [
            {
                "value": "string",
                "$ref": "string",
                "display": "string"
            }
        ],
        "entitlements": [
            {
                "value": "string",
                "display": "string"
            }
        ]
    },
    "schemas": [
        "string"
    ]
}
Authorizations:
bearerAuth
path Parameters
userId
required
string
header Parameters
Content-Type
string
Example: application/scim+json

Responses

Response samples

Content type
application/scim+json
{}

Update a user

PUT /scim/v2/Users/{userId}

This endpoint allows you to update the details of a user.

For security reasons password cannot be set via API.

Request Body

  • schemas (array, required): An array of schema URLs.

  • userName (string, required): The username of the user.

  • name (object, required): The name of the user, including given name and family name.

    • givenName (string, required): The given name of the user.

    • familyName (string, required): The family name of the user.

  • externalId (string): The external ID of the user.

  • active (boolean): Indicates whether the user is active.

  • groups (array, required): An array of groups that the user belongs to.

    • value (string, required): The id of the group.

  • entitlements (array, required): An array of library permissions the user has access to.

    • value (string, required): The name of the permission.

Response Body

The response is a JSON object conforming to the following schema:

{
  "id": "string",
  "externalId": "string",
  "meta": {
    "created": "string",
    "lastModified": "string",
    "location": "string",
    "resourceType": "string"
  },
  "urn:ietf:params:scim:schemas:core:2.0:User": {
    "userName": "string",
    "name": {
      "formatted": "string",
      "familyName": "string",
      "givenName": "string"
    },
    "active": true,
    "groups": [
      {
        "value": "string",
        "$ref": "string",
        "display": "string"
      }
    ],
    "entitlements": [
      {
        "value": "string",
        "display": "string"
      }
    ],
  },
  "schemas": ["string"]
}
Authorizations:
bearerAuth
path Parameters
userId
required
string
header Parameters
Content-Type
string
Example: application/scim+json
Request Body schema: application/scim+json
schemas
Array of any
Default: ["urn:ietf:params:scim:schemas:core:2.0:User"]
Items Value: "urn:ietf:params:scim:schemas:core:2.0:User"
userName
string <email>
object
externalId
string
active
boolean
Array of objects
Array of objects

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "userName": "example@stensul.com",
  • "name": {
    },
  • "externalId": "some-unique-id",
  • "active": true,
  • "groups": [
    ],
  • "entitlements": [
    ]
}

Response samples

Content type
application/scim+json
{
  • "id": "663a829c778347154f045a7c",
  • "externalId": "some-unique-id",
  • "meta": {},
  • "urn:ietf:params:scim:schemas:core:2.0:User": {
    },
  • "schemas": [
    ]
}

Delete a user

DELETE /scim/v2/Users/{userId}

This endpoint is used to delete a specific user by their ID.

Request Body

  • Method: DELETE

  • Endpoint: {baseUrl}/scim/v2/Users/{userId}

Response Body

The response for this request is in JSON format and includes the following schema:

{
    "type": "object",
    "properties": {
        "schemas": {
            "type": "array"
        },
        "detail": {
            "type": "string"
        },
        "status": {
            "type": "integer"
        }
    }
}

The response will have a status code of 404 if the user with the specified ID is not found.

Authorizations:
bearerAuth
path Parameters
userId
required
string
header Parameters
Content-Type
string
Example: application/scim+json

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "detail": "Resource \"6669edf917fbcd961603a392\" not found",
  • "status": 404
}

Update some user's fields

PATCH /scim/v2/Users/{userId}

This endpoint is used to update a specific user's information using the SCIM (System for Cross-domain Identity Management) protocol.

Request Body

  • schemas (array of strings, required): An array of URNs that indicate the schema used for the request.

  • Operations (array of objects, required): An array of operations to be performed on the user's information.

    • op (string, required): The operation to be performed, e.g., "replace", "add" or "remove".

    • value (object, required): The updated value for the specified attribute.

      • active (boolean): Indicates whether the user is active or not.

      • userName (string): The username of the user.

      • externalId (string): The unique identifier for the user outside Stensul.

      • groups (array of objects): An array of groups to which the user belongs.

        • value (string, required): The unique identifier of the group.

      • entitlements (array, required): An array of library permissions the user has access to.

        • value (string, required): The name of the permission.

    • path (string, required if "op" is "add" or "remove"): The path of the attribute to be updated, e.g., "name.givenName".

    • value (string, required): The updated value for the specified attribute.

Response Body

The response of this request will conform to a JSON schema that represents the updated user information.

{
    "id": "string",
    "externalId": "string",
    "meta": {
        "created": "string",
        "lastModified": "string",
        "location": "string",
        "resourceType": "string"
    },
    "urn:ietf:params:scim:schemas:core:2.0:User": {
        "userName": "string",
        "name": {
            "formatted": "string",
            "familyName": "string",
            "givenName": "string"
        },
        "active": true,
        "groups": [
            {
                "value": "string",
                "$ref": "string",
                "display": "string"
            }
        ],
        "entitlements": [
            {
                "value": "string",
                "display": "string"
            }
        ]
    },
    "schemas": [
        "string"
    ]
}
Authorizations:
bearerAuth
path Parameters
userId
required
string
header Parameters
Content-Type
string
Example: application/scim+json
Request Body schema: application/scim+json
object

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "Operations": [
    ]
}

Response samples

Content type
application/scim+json
{}

Create a user

POST /scim/v2/Users

This endpoint is used to create a new user in the system.

For security reasons passwords cannot be set via API, upon first login the user will be forced to set a new password.

Request Body

  • schemas (array of strings, required): An array of strings indicating the names of the SCIM schemas supported.

  • externalId (string, optional): An optional Id used to identify the user in a system other than Stensul.

  • userName (string, required): Email used to identify the user in Stensul.

  • name (object, required): The user's name object containing the given name and family name.

    • givenName (string, required): The user's given name.

    • familyName (string, required): The user's family name.

  • active (boolean): Indicates whether the user is active.

  • groups (array of objects, required): An array of group objects that the user belongs to.

    • value (string, required): The identifier of the group.

  • entitlements (array, required): An array of library permissions the user has access to.

    • value (string, required): The name of the permission.

Response Body

The response will be in the form of a JSON schema representing the newly created user with the following properties:

  • id (string): The unique identifier of the user.

  • externalId (string): The external Id used to identify the user in a system other than Stensul.

  • meta (object): Metadata object containing information about the user's creation and modification.

    • created (string): The timestamp when the user was created.

    • lastModified (string): The timestamp when the user was last modified.

    • location (string): The location of the user resource.

    • resourceType (string): The type of the user resource.

  • urn:ietf:params:scim:schemas:core:2.0:User (object): The user object with the following properties:

    • userName (string): Email used to identify the user in Stensul.

    • name (object): The user's name object.

      • formatted (string): The formatted name of the user.

      • familyName (string): The user's family name.

      • givenName (string): The user's given name.

    • active (boolean): Indicates whether the user is active.

    • groups (array of objects): An array of group objects that the user belongs to.

      • value (string): The identifier of the group.

      • $ref (string): The reference to the group.

      • display (string): The display name of the group.

  • schemas (array of strings): An array of strings indicating the names of the SCIM schemas supported by the user.

Example Response

{
    "id": "666b040717fbcd961603a49a",
    "externalId": "some-unique-id",
    "meta": {
        "created": "2024-06-13T10:36:55-04:00",
        "lastModified": "2024-06-13T10:36:55-04:00",
        "location": "https://mycompany.stensul.com/scim/v2/Users/666b040717fbcd961603a49a",
        "resourceType": "User"
    },
    "urn:ietf:params:scim:schemas:core:2.0:User": {
        "userName": "example1@stensul.com",
        "name": {
            "formatted": "John Doe",
            "familyName": "Doe",
            "givenName": "John"
        },
        "active": true,
        "groups": [
            {
                "value": "6176ca93290d332c4c35f671",
                "$ref": "https://mycompany.stensul.com/scim/v2/Groups/6176ca93290d332c4c35f671",
                "display": "admin"
            },
            {
                "value": "6176ca93290d332c4c35f66f",
                "$ref": "https://mycompany.stensul.com/scim/v2/Groups/6176ca93290d332c4c35f66f",
                "display": "full"
            }
        ],
        "entitlements": [
          {
            "value": "",
            "display": ""
          }
        ],
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ]
}
Authorizations:
bearerAuth
header Parameters
Content-Type
string
Example: application/scim+json
Request Body schema: application/scim+json
schemas
Array of any
Default: ["urn:ietf:params:scim:schemas:core:2.0:User"]
Items Value: "urn:ietf:params:scim:schemas:core:2.0:User"
userName
string <email>
object
externalId
string
active
boolean
Array of objects
Array of objects

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "externalId": "some-unique-id",
  • "userName": "example@stensul.com",
  • "name": {
    },
  • "active": true,
  • "groups": [
    ],
  • "entitlements": [
    ]
}

Response samples

Content type
application/scim+json
{}

Get all user resources

GET /scim/v2/Users

This endpoint retrieves a list of users with the ability to paginate the results based on the filter criteria.

Request Body

  • Method: GET

  • URL: {baseUrl}/scim/v2/Users

  • Query Parameters:

    • filter (string, optional): The filter criteria for retrieving users.

    • startIndex (integer, optional): The index of the first result to return.

    • count (integer, optional): The number of results to return.

    • sortBy (string, optional): The attribute to sort the results by. Supported values are "id", "externalId", "meta.created", "meta.lastModified", "userName", "name.familyName" and "name.givenName".

    • sortOrder (string, optional): The order to sort the results in. Allowed values are "ascending" or "descending".

Response Body

The response is in JSON format and follows the SCIM (System for Cross-domain Identity Management) standard. Below is a JSON schema representing the response:

{
  "type": "object",
  "properties": {
    "totalResults": {
      "type": "integer"
    },
    "itemsPerPage": {
      "type": "integer"
    },
    "startIndex": {
      "type": "integer"
    },
    "schemas": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "Resources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "externalId": {
            "type": "string"
          },
          "meta": {
            "type": "object",
            "properties": {
              "created": {
                "type": "string",
                "format": "date-time"
              },
              "lastModified": {
                "type": "string",
                "format": "date-time"
              },
              "location": {
                "type": "string"
              },
              "resourceType": {
                "type": "string"
              }
            }
          },
          "urn:ietf:params:scim:schemas:core:2.0:User": {
            "type": "object",
            "properties": {
              "userName": {
                "type": "string"
              },
              "name": {
                "type": "object",
                "properties": {
                  "formatted": {
                    "type": "string"
                  },
                  "familyName": {
                    "type": "string"
                  },
                  "givenName": {
                    "type": "string"
                  }
                }
              },
              "active": {
                "type": "boolean"
              },
              "groups": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "string"
                    },
                    "$ref": {
                      "type": "string"
                    },
                    "display": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "schemas": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
Authorizations:
bearerAuth
query Parameters
startIndex
integer
count
integer
Example: count=10
sortBy
string
Enum: "id" "userName" "externalId" "meta.created" "meta.lastModified" "name.familyName" "name.givenName"
Example: sortBy=userName

The attribute to sort the results by. Supported values are "id", "externalId", "meta.created", "meta.lastModified", "userName", "name.familyName" and "name.givenName".

sortOrder
string
Enum: "ascending" "descending"
Example: sortOrder=ascending

The order to sort the results in. Allowed values are "ascending" or "descending".

header Parameters
Content-Type
string
Example: application/scim+json

Responses

Response samples

Content type
application/scim+json
{}

SCIM - Group Provisioning

Manage Stensul Roles

Get all group resources

GET /scim/v2/Groups

This endpoint retrieves a list of groups with the ability to paginate the results based on the filter criteria.

Request Body

  • Method: GET

  • URL: {baseUrl}/scim/v2/Groups

  • Query Parameters:

    • filter (string, optional): The filter criteria for retrieving groups. "id", "displayName" and "members" are supported. Filter values are case insensitive.

    • startIndex (integer, optional): The index of the first result to return.

    • count (integer, optional): The number of results to return.

    • sortBy (string, optional): The attribute to sort the results by. Supported values are "id", "displayName", "meta.created", "meta.lastModified".

    • sortOrder (string, optional): The order to sort the results in. Allowed values are "ascending" or "descending".

Response Body

The response is in JSON format with the following schema:

{
  "type": "object",
  "properties": {
    "totalResults": {
      "type": "integer"
    },
    "itemsPerPage": {
      "type": "integer"
    },
    "startIndex": {
      "type": "integer"
    },
    "schemas": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "Resources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "meta": {
            "type": "object",
            "properties": {
              "created": {
                "type": "string"
              },
              "lastModified": {
                "type": "string"
              },
              "location": {
                "type": "string"
              },
              "resourceType": {
                "type": "string"
              }
            }
          },
          "schemas": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "urn:ietf:params:scim:schemas:core:2.0:Group": {
            "type": "object",
            "properties": {
              "displayName": {
                "type": "string"
              },
              "members": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "string"
                    },
                    "$ref": {
                      "type": "string"
                    },
                    "display": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
Authorizations:
bearerAuth
query Parameters
startIndex
integer

The index entry by which to begin the list of returned results.

count
integer
Example: count=10

Limit the number of results returned in a single response. By default, the system returns a list of 100 users.

filter
string
Example: filter=displayName eq "full"

Filter results by a specific word or phrase. Filter values are case-insensitive. This query parameter supports "id", "displayName" and "members"

sortBy
string
Enum: "id" "displayName" "meta.created" "meta.lastModified"
Example: sortBy=displayName

The attribute to sort the results by. Supported values are "id", "displayName", "meta.created", "meta.lastModified".

sortOrder
string
Enum: "ascending" "descending"
Example: sortOrder=ascending

The order to sort the results in. Allowed values are "ascending" or "descending".

header Parameters
Content-Type
string
Example: application/scim+json

Responses

Response samples

Content type
application/scim+json
{}

Create a group

POST /scim/v2/Groups

This endpoint is used to create a new group in the system.

Request Body

  • schemas (array of strings, required): An array of strings indicating the names of the SCIM schemas supported.

  • displayName (string, required): Group name.

  • members (array of objects, optional): An array of user objects.

    • value (string, required): The identifier of the user.

Response Body

The response will be in the form of a JSON schema representing the newly created group with the following properties:

  • id (string): The unique identifier of the group.

  • meta (object): Metadata object containing information about the group's creation and modification.

    • created (string): The timestamp when the group was created.

    • lastModified (string): The timestamp when the group was last modified.

    • location (string): The location of the group resource.

    • resourceType (string): The type of the group resource.

  • urn:ietf:params:scim:schemas:core:2.0:Group (object): The group object with the following properties:

    • displayName (string): Group name.

    • members (array of objects): An array of user objects members of the group.

      • value (string): The identifier of the user.

      • $ref (string): The reference to the user.

      • display (string): The display name of the user.

  • schemas (array of strings): An array of strings indicating the names of the SCIM schemas supported by the group.

Example Response

{
    "id": "668c478922b4533ad40f2e7a",
    "meta": {
        "created": "2024-07-08T16:09:45-04:00",
        "lastModified": "2024-07-08T16:09:45-04:00",
        "location": "https://mycompany.stensul.com/scim/v2/Groups/668c478922b4533ad40f2e7a",
        "resourceType": "Group"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "urn:ietf:params:scim:schemas:core:2.0:Group": {
        "displayName": "SCIM Group",
        "members": [
            {
                "value": "667adbb640ee4dd72b006655",
                "$ref": "https://mycompany.stensul.com/scim/v2/Users/667adbb640ee4dd72b006655",
                "display": "John Doe"
            }
        ]
    }
}
Authorizations:
bearerAuth
header Parameters
Content-Type
string
Example: application/scim+json
Request Body schema: application/scim+json
schemas
Array of any
Default: ["urn:ietf:params:scim:schemas:core:2.0:Group"]
Items Value: "urn:ietf:params:scim:schemas:core:2.0:Group"
displayName
string
Array of objects

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "displayName": "SCIM Group",
  • "members": [
    ]
}

Response samples

Content type
application/scim+json
{}

Update a group

PUT /scim/v2/Groups

This endpoint allows you to update the details of a group.

Request Body

  • schemas (array, required): An array of schema URLs.

  • displayName (string, required): The name of the group.

  • members (array, optional): An array of members of the group.

    • value (string, required): The id of the user.

Response Body

The response is a JSON object conforming to the following schema:

{
  "id": "string",
  "meta": {
    "created": "string",
    "lastModified": "string",
    "location": "string",
    "resourceType": "string"
  },
  "urn:ietf:params:scim:schemas:core:2.0:Group": {
    "displayName": "string",
    "members": [
      {
        "value": "string",
        "$ref": "string",
        "display": "string"
      }
    ],
  },
  "schemas": ["string"]
}
Authorizations:
bearerAuth
path Parameters
groupId
required
string
header Parameters
Content-Type
string
Example: application/scim+json
Request Body schema: application/scim+json
schemas
Array of any
Default: ["urn:ietf:params:scim:schemas:core:2.0:Group"]
Items Value: "urn:ietf:params:scim:schemas:core:2.0:Group"
displayName
string
Array of objects

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "displayName": "SCIM Group",
  • "members": [
    ]
}

Response samples

Content type
application/scim+json
{}

Update a group's field

PATCH /scim/v2/Groups/{groupId}

This endpoint is used to update a specific group's information using the SCIM (System for Cross-domain Identity Management) protocol.

Request Body

  • schemas (array of strings, required): An array of URNs that indicate the schema used for the request.

  • Operations (array of objects, required): An array of operations to be performed on the group's information.

    • op (string, required): The operation to be performed, e.g., "replace", "add" or "remove".

    • value (object, required): The updated value for the specified attribute.

      • displayName (string): The name of the group.

      • members (array of objects): An array of users for the group.

        • value (string, required): The unique identifier of the user.

    • path (string, required if "op" is "add" or "remove"): The path of the attribute to be updated, e.g., "members".

    • value (string, required): The updated value for the specified attribute.

Response Body

The response of this request will conform to a JSON schema that represents the updated user information.

{
    "id": "string",
    "meta": {
        "created": "string",
        "lastModified": "string",
        "location": "string",
        "resourceType": "string"
    },
    "schemas": [
        "string"
    ],
    "urn:ietf:params:scim:schemas:core:2.0:Group": {
        "displayName": "string",
        "members": [
            {
                "value": "string",
                "$ref": "string",
                "display": "string"
            }
        ]
    }
}
Authorizations:
bearerAuth
path Parameters
groupId
required
string
header Parameters
Content-Type
string
Example: application/scim+json
Request Body schema: application/scim+json
object

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "Operations": [
    ]
}

Response samples

Content type
application/scim+json
{}

Get a group resource

GET /scim/v2/Groups/{groupId}

This endpoint retrieves information about a specific group identified by the groupId.

Request Body

No request body is required for this endpoint. The groupId path parameter should be provided in the URL.

Response Body

The response will be in JSON format with the following schema:

{
    "id": "id",
    "meta": {
        "created": "string",
        "lastModified": "string",
        "location": "string",
        "resourceType": "string"
    },
    "schemas": ["string"],
    "urn:ietf:params:scim:schemas:core:2.0:Group": {
        "displayName": "string",
        "members": [
            {
                "value": "string",
                "$ref": "string",
                "display": "string"
            }
        ]
    }
}

The response will contain details about the group including its ID, creation and modification metadata, name, and members.

Authorizations:
bearerAuth
path Parameters
groupId
required
string
header Parameters
Content-Type
string
Example: application/scim+json

Responses

Response samples

Content type
application/scim+json
{}

Delete a group

DELETE /scim/v2/Groups/{groupId}

This endpoint is used to delete a specific group by its ID.

Request Body

  • Method: DELETE

  • Endpoint: {baseUrl}/scim/v2/Groups/{groupId}

Response Body

The response for this request is in JSON format and includes the following schema:

{
    "type": "object",
    "properties": {
        "schemas": {
            "type": "array"
        },
        "detail": {
            "type": "string"
        },
        "status": {
            "type": "integer"
        }
    }
}

The response will have a status code of 404 if the group with the specified ID is not found.

Authorizations:
bearerAuth
path Parameters
groupId
required
string
header Parameters
Content-Type
string
Example: application/scim+json

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "detail": "Resource \"6686fbbeccd0a3cca10f1cda\" not found",
  • "status": 404
}

SCIM - Schemas

Resource Schema Definitions

User

GET /scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User

This endpoint retrieves the schema for the User resource in the SCIM API.

Request Body

No request body parameters are required for this endpoint.

Response Body

The response for this request is in the form of a JSON schema, providing the structure and attributes for the User resource. An example response is as follows:

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Schema"
    ],
    "id": "urn:ietf:params:scim:schemas:core:2.0:User",
    "meta": {
        "resourceType": "Schema",
        "created": "2001-01-01T00:00:00+00:00",
        "lastModified": "2001-01-01T00:00:00+00:00",
        "version": "W/\"5CF43FF3C1E0C85DE1F13305C3B1AC83009FF941\"",
        "location": "https://mycompany.stensul.com/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
    },
    "name": "User",
    "description": "User resource.",
    "attributes": [
        {
            "name": "userName",
            "description": "Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. REQUIRED.",
            "type": "string",
            "mutability": "readWrite",
            "returned": "default",
            "uniqueness": "server",
            "required": true,
            "multiValued": false,
            "caseExact": false
        },
        {
            "name": "name",
            "description": "The components of the user's real name. Providers MAY return just the full name as a single string in the formatted sub-attribute, or they MAY return just the individual component attributes using the other sub-attributes, or they MAY return both. If both variants are returned, they SHOULD be describing the same name, with the formatted name indicating how the component attributes should be combined.",
            "type": "complex",
            "mutability": "readWrite",
            "returned": "default",
            "uniqueness": "none",
            "required": true,
            "multiValued": false,
            "caseExact": false,
            "subAttributes": [
                {
                    "name": "formatted",
                    "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g., 'Ms. Barbara J Jensen, III'].",
                    "type": "string",
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": false,
                    "multiValued": false,
                    "caseExact": false
                },
                {
                    "name": "familyName",
                    "description": "The family name of the User, or last name in most Western languages (e.g., 'Jensen' given the full name 'Ms. Barbara J Jensen, III'].",
                    "type": "string",
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": true,
                    "multiValued": false,
                    "caseExact": false
                },
                {
                    "name": "givenName",
                    "description": "The given name of the User, or first name in most Western languages (e.g., 'Barbara' given the full name 'Ms. Barbara J Jensen, III'].",
                    "type": "string",
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": true,
                    "multiValued": false,
                    "caseExact": false
                }
            ]
        },
        {
            "name": "active",
            "description": "A Boolean value indicating the User's administrative status.",
            "type": "boolean",
            "mutability": "readWrite",
            "returned": "default",
            "required": false,
            "multiValued": false,
            "caseExact": false
        },
        {
            "name": "groups",
            "description": "A list of groups to which the user belongs, either through direct membership, through nested groups, or dynamically calculated.",
            "type": "complex",
            "mutability": "readOnly",
            "returned": "default",
            "uniqueness": "none",
            "required": true,
            "multiValued": true,
            "caseExact": false,
            "subAttributes": [
                {
                    "name": "value",
                    "description": "The identifier of the User's group.",
                    "type": "string",
                    "mutability": "readOnly",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": true,
                    "multiValued": false,
                    "caseExact": false
                },
                {
                    "name": "$ref",
                    "description": "The URI of the corresponding 'Group' resource to which the user belongs.",
                    "type": "reference",
                    "mutability": "readOnly",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": false,
                    "multiValued": false,
                    "caseExact": false,
                    "referenceTypes": [
                        "Group"
                    ]
                },
                {
                    "name": "display",
                    "description": "A human-readable name, primarily used for display purposes. READ-ONLY.",
                    "type": "string",
                    "mutability": "readOnly",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": false,
                    "multiValued": false,
                    "caseExact": false
                }
            ]
        }
    ]
}
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "id": "urn:ietf:params:scim:schemas:core:2.0:User",
  • "meta": {},
  • "name": "User",
  • "description": "User resource.",
  • "attributes": [
    ]
}

Group

GET /scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group

This endpoint retrieves the schema for the SCIM group resource.

Request Body

This endpoint does not require any request body.

Response Body

The response is a JSON schema representing the SCIM group resource, with the following structure:

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Schema"
    ],
    "id": "urn:ietf:params:scim:schemas:core:2.0:Group",
    "meta": {
        "resourceType": "Schema",
        "created": "2001-01-01T00:00:00+00:00",
        "lastModified": "2001-01-01T00:00:00+00:00",
        "version": "W/\"05A8B9B6C912798878B44A358F579A083EF9C4A3\"",
        "location": "https://mycompany.stensul.com/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
    },
    "name": "Group",
    "description": "Group resource.",
    "attributes": [
        {
            "name": "displayName",
            "description": "A human-readable name for the Group. REQUIRED.",
            "type": "string",
            "mutability": "readWrite",
            "returned": "default",
            "uniqueness": "none",
            "required": true,
            "multiValued": false,
            "caseExact": false
        },
        {
            "name": "members",
            "description": "A list of members of the Group.",
            "type": "complex",
            "mutability": "readWrite",
            "returned": "default",
            "uniqueness": "none",
            "required": false,
            "multiValued": true,
            "caseExact": false,
            "subAttributes": [
                {
                    "name": "type",
                    "description": "A label indicating the type of resource, e.g., 'User' or 'Group'.",
                    "type": "string",
                    "mutability": "immutable",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": false,
                    "multiValued": false,
                    "caseExact": false,
                    "canonicalValues": [
                        "User",
                        "Group"
                    ]
                },
                {
                    "name": "display",
                    "description": "Display name for the member",
                    "type": "string",
                    "mutability": "immutable",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": false,
                    "multiValued": false,
                    "caseExact": false
                },
                {
                    "name": "value",
                    "description": "Identifier of the member of this Group.",
                    "type": "string",
                    "mutability": "immutable",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": false,
                    "multiValued": false,
                    "caseExact": false
                },
                {
                    "name": "$ref",
                    "description": "The URI corresponding to a SCIM resource that is a member of this Group.",
                    "type": "reference",
                    "mutability": "immutable",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": false,
                    "multiValued": false,
                    "caseExact": false,
                    "referenceTypes": [
                        "User",
                        "Group"
                    ]
                }
            ]
        }
    ]
}
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "id": "urn:ietf:params:scim:schemas:core:2.0:Group",
  • "meta": {},
  • "name": "Group",
  • "description": "Group resource.",
  • "attributes": [
    ]
}

List

GET /scim/v2/Schemas

This endpoint retrieves the SCIM (System for Cross-domain Identity Management) schemas.

Response Body

The response is a JSON object with the following structure:

  • totalResults (integer): The total number of results.

  • itemsPerPage (integer): The number of items per page.

  • startIndex (integer): The start index of the results.

  • schemas (array of strings): An array of schema names.

  • Resources (array): An array of resource objects, each with the following properties:

    • schemas (array of strings): An array of schema names for the resource.

    • id (string): The ID of the resource.

    • meta (object): An object containing metadata for the resource, with the following properties:

      • resourceType (string): The type of the resource.

      • created (string): The creation timestamp.

      • lastModified (string): The last modification timestamp.

      • version (string): The version of the resource.

      • location (string): The location of the resource.

    • name (string): The name of the resource.

    • description (string): The description of the resource.

    • attributes (array): An array of attribute objects, each with the following properties:

      • name (string): The name of the attribute.

      • description (string): The description of the attribute.

      • type (string): The type of the attribute.

      • mutability (string): The mutability of the attribute.

      • returned (string): The attribute's returned behavior.

      • uniqueness (string): The uniqueness constraint of the attribute.

      • required (boolean): Indicates if the attribute is required.

      • multiValued (boolean): Indicates if the attribute is multi-valued.

      • caseExact (boolean): Indicates if the attribute is case-sensitive.

Example

{
    "totalResults": 2,
    "itemsPerPage": 2,
    "startIndex": 1,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Schema"
            ],
            "id": "urn:ietf:params:scim:schemas:core:2.0:User",
            "meta": {
                "resourceType": "Schema",
                "created": "2001-01-01T00:00:00+00:00",
                "lastModified": "2001-01-01T00:00:00+00:00",
                "version": "W/\"5CF43FF3C1E0C85DE1F13305C3B1AC83009FF941\"",
                "location": "https://mycompany.stensul.com/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
            },
            "name": "User",
            "description": "User resource.",
            "attributes": [
                {
                    "name": "userName",
                    "description": "Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. REQUIRED.",
                    "type": "string",
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "server",
                    "required": true,
                    "multiValued": false,
                    "caseExact": false
                },
                {
                    "name": "name",
                    "description": "The components of the user's real name. Providers MAY return just the full name as a single string in the formatted sub-attribute, or they MAY return just the individual component attributes using the other sub-attributes, or they MAY return both. If both variants are returned, they SHOULD be describing the same name, with the formatted name indicating how the component attributes should be combined.",
                    "type": "complex",
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": true,
                    "multiValued": false,
                    "caseExact": false,
                    "subAttributes": [
                        {
                            "name": "formatted",
                            "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g., 'Ms. Barbara J Jensen, III'].",
                            "type": "string",
                            "mutability": "readWrite",
                            "returned": "default",
                            "uniqueness": "none",
                            "required": false,
                            "multiValued": false,
                            "caseExact": false
                        },
                        {
                            "name": "familyName",
                            "description": "The family name of the User, or last name in most Western languages (e.g., 'Jensen' given the full name 'Ms. Barbara J Jensen, III'].",
                            "type": "string",
                            "mutability": "readWrite",
                            "returned": "default",
                            "uniqueness": "none",
                            "required": true,
                            "multiValued": false,
                            "caseExact": false
                        },
                        {
                            "name": "givenName",
                            "description": "The given name of the User, or first name in most Western languages (e.g., 'Barbara' given the full name 'Ms. Barbara J Jensen, III'].",
                            "type": "string",
                            "mutability": "readWrite",
                            "returned": "default",
                            "uniqueness": "none",
                            "required": true,
                            "multiValued": false,
                            "caseExact": false
                        }
                    ]
                },
                {
                    "name": "active",
                    "description": "A Boolean value indicating the User's administrative status.",
                    "type": "boolean",
                    "mutability": "readWrite",
                    "returned": "default",
                    "required": false,
                    "multiValued": false,
                    "caseExact": false
                },
                {
                    "name": "groups",
                    "description": "A list of groups to which the user belongs, either through direct membership, through nested groups, or dynamically calculated.",
                    "type": "complex",
                    "mutability": "readOnly",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": true,
                    "multiValued": true,
                    "caseExact": false,
                    "subAttributes": [
                        {
                            "name": "value",
                            "description": "The identifier of the User's group.",
                            "type": "string",
                            "mutability": "readOnly",
                            "returned": "default",
                            "uniqueness": "none",
                            "required": true,
                            "multiValued": false,
                            "caseExact": false
                        },
                        {
                            "name": "$ref",
                            "description": "The URI of the corresponding 'Group' resource to which the user belongs.",
                            "type": "reference",
                            "mutability": "readOnly",
                            "returned": "default",
                            "uniqueness": "none",
                            "required": false,
                            "multiValued": false,
                            "caseExact": false,
                            "referenceTypes": [
                                "Group"
                            ]
                        },
                        {
                            "name": "display",
                            "description": "A human-readable name, primarily used for display purposes. READ-ONLY.",
                            "type": "string",
                            "mutability": "readOnly",
                            "returned": "default",
                            "uniqueness": "none",
                            "required": false,
                            "multiValued": false,
                            "caseExact": false
                        }
                    ]
                }
            ]
        },
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Schema"
            ],
            "id": "urn:ietf:params:scim:schemas:core:2.0:Group",
            "meta": {
                "resourceType": "Schema",
                "created": "2001-01-01T00:00:00+00:00",
                "lastModified": "2001-01-01T00:00:00+00:00",
                "version": "W/\"05A8B9B6C912798878B44A358F579A083EF9C4A3\"",
                "location": "https://mycompany.stensul.com/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
            },
            "name": "Group",
            "description": "Group resource.",
            "attributes": [
                {
                    "name": "displayName",
                    "description": "A human-readable name for the Group. REQUIRED.",
                    "type": "string",
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": true,
                    "multiValued": false,
                    "caseExact": false
                },
                {
                    "name": "members",
                    "description": "A list of members of the Group.",
                    "type": "complex",
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none",
                    "required": false,
                    "multiValued": true,
                    "caseExact": false,
                    "subAttributes": [
                        {
                            "name": "type",
                            "description": "A label indicating the type of resource, e.g., 'User' or 'Group'.",
                            "type": "string",
                            "mutability": "immutable",
                            "returned": "default",
                            "uniqueness": "none",
                            "required": false,
                            "multiValued": false,
                            "caseExact": false,
                            "canonicalValues": [
                                "User",
                                "Group"
                            ]
                        },
                        {
                            "name": "display",
                            "description": "Display name for the member",
                            "type": "string",
                            "mutability": "immutable",
                            "returned": "default",
                            "uniqueness": "none",
                            "required": false,
                            "multiValued": false,
                            "caseExact": false
                        },
                        {
                            "name": "value",
                            "description": "Identifier of the member of this Group.",
                            "type": "string",
                            "mutability": "immutable",
                            "returned": "default",
                            "uniqueness": "none",
                            "required": false,
                            "multiValued": false,
                            "caseExact": false
                        },
                        {
                            "name": "$ref",
                            "description": "The URI corresponding to a SCIM resource that is a member of this Group.",
                            "type": "reference",
                            "mutability": "immutable",
                            "returned": "default",
                            "uniqueness": "none",
                            "required": false,
                            "multiValued": false,
                            "caseExact": false,
                            "referenceTypes": [
                                "User",
                                "Group"
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}
Authorizations:
bearerAuth
header Parameters
Content-Type
string
Example: application/scim+json

Responses

Response samples

Content type
application/scim+json
{
  • "totalResults": 2,
  • "itemsPerPage": 2,
  • "startIndex": 1,
  • "schemas": [
    ],
  • "Resources": [
    ]
}

SCIM - Resource Types

Resource Type Definitions

Get resource types

GET /scim/v2/ResourceTypes

This endpoint retrieves the resource types available in the system.

Valid resource types include Users and Groups.

Request

No request body is required for this endpoint.

Response

The response will be in JSON format with the following schema:

{
    "totalResults": integer,
    "itemsPerPage": integer,
    "startIndex": integer,
    "schemas": [string],
    "Resources": [
        {
            "schemas": [string],
            "id": string,
            "name": string,
            "endpoint": string,
            "description": string,
            "schema": string,
            "schemaExtensions": [array],
            "meta": {
                "location": string,
                "resourceType": string
            }
        }
    ]
}

The totalResults field indicates the total number of results available. Each Resource object contains information about a specific resource type, including its id, name, endpoint, description, schema, schemaExtensions, and meta information.

Example response:

{
    "totalResults": 2,
    "itemsPerPage": 2,
    "startIndex": 1,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
            ],
            "id": "User",
            "name": "Users",
            "endpoint": "https://mycompany.stensul.com/scim/v2/Users",
            "description": "User Account",
            "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
            "schemaExtensions": [],
            "meta": {
                "location": "https://mycompany.stensul.com/scim/v2/ResourceTypes/User",
                "resourceType": "ResourceType"
            }
        },
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
            ],
            "id": "Group",
            "name": "Groups",
            "endpoint": "https://mycompany.stensul.com/scim/v2/Groups",
            "description": "Group",
            "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
            "schemaExtensions": [],
            "meta": {
                "location": "https://mycompany.stensul.com/scim/v2/ResourceTypes/Group",
                "resourceType": "ResourceType"
            }
        }
    ]
}
Authorizations:
bearerAuth
header Parameters
Content-Type
string
Example: application/scim+json

Responses

Response samples

Content type
application/scim+json
{}

Get User Resource Type

GET /scim/v2/ResourceTypes/User

This endpoint retrieves the details of a specific resource type, in this case, the "User" resource type.

Request

No request body is required for this endpoint.

Response

The response for this request is in the form of a JSON schema, with the following structure:

  • schemas (array): An array of strings representing the schemas supported by the resource type.

  • id (string): The unique identifier for the resource type.

  • name (string): The name of the resource type.

  • endpoint (string): The endpoint for the resource type.

  • description (string): A description of the resource type.

  • schema (string): The schema associated with the resource type.

  • schemaExtensions (array): An array of schema extensions for the resource type.

  • meta (object): An object containing metadata for the resource type, including the location and resource type.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
    ],
    "id": "User",
    "name": "Users",
    "endpoint": "https://mycompany.stensul.com/scim/v2/Users",
    "description": "User Account",
    "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
    "schemaExtensions": [],
    "meta": {
        "location": "https://mycompany.stensul.com/scim/v2/ResourceTypes/User",
        "resourceType": "ResourceType"
    }
}
Authorizations:
bearerAuth
header Parameters
Content-Type
string
Example: application/scim+json

Responses

Response samples

Content type
application/scim+json
{}

Get Group Resource Type

GET /scim/v2/ResourceTypes/Group

This endpoint retrieves the details of a specific resource type, in this case, the "Group" resource type.

Request

No request body is required for this endpoint.

Response

The response for this request is in the form of a JSON schema, with the following structure:

  • schemas (array): An array of strings representing the schemas supported by the resource type.

  • id (string): The unique identifier for the resource type.

  • name (string): The name of the resource type.

  • endpoint (string): The endpoint for the resource type.

  • description (string): A description of the resource type.

  • schema (string): The schema associated with the resource type.

  • schemaExtensions (array): An array of schema extensions for the resource type.

  • meta (object): An object containing metadata for the resource type, including the location and resource type.

Example response:

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
    ],
    "id": "Group",
    "name": "Groups",
    "endpoint": "https://mycompany.stensul.com/scim/v2/Groups",
    "description": "Group",
    "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
    "schemaExtensions": [],
    "meta": {
        "location": "https://mycompany.stensul.com/scim/v2/ResourceTypes/Group",
        "resourceType": "ResourceType"
    }
}
Authorizations:
bearerAuth
header Parameters
string

Responses

Response samples

Content type
application/scim+json
{}

SCIM - Configuration

Service Provider Configuration

Get service provider configuration

GET /scim/v2/ServiceProviderConfig

This endpoint retrieves the service provider configuration.

Response Body

The response is in JSON format and follows the SCIM (System for Cross-domain Identity Management) schema. It includes the following fields:

  • schemas (array): An array of strings representing the supported schemas.

  • patch (object): Indicates if the PATCH operation is supported.

  • bulk (object): Indicates if the bulk operations are supported, along with the maximum payload size and maximum operations.

  • filter (object): Indicates if the filter operation is supported, along with the maximum results.

  • changePassword (object): Indicates if the change password operation is supported.

  • sort (object): Indicates if the sort operation is supported.

  • etag (object): Indicates if the etag operation is supported.

  • authenticationSchemes (array): An array of authentication scheme objects, each containing the name, description, specUri, documentationUri, type, and primary flag.

  • meta (object): Contains metadata such as location, resource type, created timestamp, last modified timestamp, and version.

Example response:

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
    ],
    "patch": {
        "supported": true
    },
    "bulk": {
        "supported": true,
        "maxPayloadSize": 1048576,
        "maxOperations": 10
    },
    "filter": {
        "supported": true,
        "maxResults": 100
    },
    "changePassword": {
        "supported": false
    },
    "sort": {
        "supported": true
    },
    "etag": {
        "supported": true
    },
    "authenticationSchemes": [
        {
            "name": "OAuth Bearer Token",
            "description": "Authentication scheme using the OAuth Bearer Token Standard",
            "specUri": "https://www.rfc-editor.org/info/rfc6750",
            "documentationUri": "https://www.rfc-editor.org/rfc/rfc6750.html",
            "type": "oauthbearertoken",
            "primary": true
        }
    ],
    "meta": {
        "location": "https://mycompany.stensul.com/scim/v2/ServiceProviderConfig",
        "resourceType": "ServiceProviderConfig",
        "created": "2024-06-12T21:19:57+00:00",
        "lastModified": "2024-06-10T19:33:18+00:00",
        "version": "W/\"d43b06bc97a786ab2c69f688f643d1b9bbc5e44e\""
    }
}
Authorizations:
bearerAuth
header Parameters
Content-Type
string
Example: application/scim+json

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "patch": {
    },
  • "bulk": {
    },
  • "filter": {
    },
  • "changePassword": {
    },
  • "sort": {
    },
  • "etag": {
    },
  • "authenticationSchemes": [],
  • "meta": {}
}

SCIM - Bulk Actions

Bulk update resources (Users and Roles)

Bulk Actions

POST /scim/v2/Bulk

This endpoint is used to perform bulk operations on SCIM resources.

Request Body

  • schemas (array of strings, required): An array of strings indicating the names of the SCIM schemas supported.

  • method (string, required) - The method for the operation.

  • bulkId (string, optional) - The ID for the bulk operation.

  • path (string) - The path for the operation.

  • data (object, required) - The data for the operation.

    • schemas (array, required) - An array of strings.

    • userName (string, required) - The username for the operation.

    • name (object) - The name object.

      • givenName (string) - The given name.

      • familyName (string) - The family name.

    • active (boolean) - The status of the operation.

    • groups (array) - An array of groups that the user belongs to.

      • value (string) - The id of the group.

    • entitlements (array, required): An array of library permissions the user has access to.

      • value (string, required): The name of the permission.

The request body should be in raw format with the following payload:

{
  "schemas": [""],
  "Operations": [
    {
      "method": "",
      "bulkId": "",
      "path": "",
      "data": {
        "schemas": [""],
        "userName": "",
        "name": {
          "givenName": "",
          "familyName": ""
        },
        "active": true,
        "groups": [
          {
            "value": ""
          }
        ],
        "entitlements": [
            {
            "value": ""
            }
        ]
      }
    }
  ]
}

Response Body

The response is in JSON format with the following schema:

  • schemas (array) - An array of strings.

  • location (string) - The location of the operation.

  • method (string) - The method for the operation.

  • bulkId (string) - The ID for the bulk operation.

  • status (integer) - The status of the operation.

{
  "schemas": ["string"],
  "Operations": [
    {
      "location": "string",
      "method": "string",
      "bulkId": "string",
      "status": integer
    }
  ]
}
Authorizations:
bearerAuth
header Parameters
Content-Type
string
Example: application/scim+json
Request Body schema: application/scim+json
object

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "Operations": [
    ]
}

Response samples

Content type
application/scim+json
{}