Some methods return paginated results. The formatting of a paginated result is always:

{
  "pagination": {
    "next_page": "...",
    "prev_page": "...",
    "last_page": "...",
    "page": "...",
    "items": "...",
    "pages": "...",
    "from": "...",
    "to": "...",
    "count": "..."
  },
  "records": [
    ...
  ]
}

The pagination object contains metadata about the current page and links to other pages. The records array contains the actual data for the current page.

Pagination Fields

• next_page: The number of the next page (if available)

• prev_page: The number of the previous page (if available)

• last_page: The number of the last page

• page: The current page number

• items: The number of items per page

• pages: The total number of pages

• from: The starting index of the current page's items

• to: The ending index of the current page's items

• count: The total number of items across all pages

Fields that are not applicable (e.g., prev_page on the first page) will be omitted from the response.

Usage Example

Let's say you make a GET request to a paginated endpoint:

GET /api/v2/users

You might receive a response like this:

{
  "pagination": {
    "next_page": 2,
    "last_page": 5,
    "page": 1,
    "items": 100,
    "pages": 5,
    "from": 1,
    "to": 100,
    "count": 450
  },
  "users": [
    ...
  ]
}

To get the next page of results, you would make a request to:

GET /api/v2/users?page=2

The Screendesk API is REST-based and uses standard HTTP verbs and status codes. The API accepts form-encoded request bodies and returns JSON-encoded responses. All requests should be made over SSL.

If you have any question, please contact the Screendesk support.

API Endpoint

The base URL to access the Screendesk API is https://app.screendesk.io.

For example, to access the recordings endpoint, just add the endpoint to the base URL: https://app.screendesk.io/api/v1/recordings.

API Reference

Authentication

Errors

The Screendesk API uses Personal access tokens to authenticate requests.

Create an access token

To create an access token, sign in to your Screendesk account and go to the "Personal Settings" page. In the “API Tokens” tab click the “Create an API Token” button.

Enter a token name and click on the “Create token” button. Once the token gets created, you will be able to copy the token to your clipboard.

You should now see the new token information in the table. You are able to view the raw token anytime you need to, as well as edit the token name and revoke the token.

How to use your access token

Once you have created your access token, you can use it to make requests to the API. Requests are authenticated using HTTP Bearer Authentication. You must provide the access token in the Authorization header:

Authorization: Bearer {ACCESS_TOKEN}

Here you can find a list of the different endpoints available to use across the Screendesk API. Click into each card to learn more.

Objects

All endpoints require authentication. Ensure you include the appropriate authentication headers with each request.

Please contact support@screendesk.io to get a token for SCIM. Token cannot be obtained through the Screendesk dashboard.

This document outlines the SCIM (System for Cross-domain Identity Management) API endpoints for user management. The API uses SCIM 2.0 schemas and conventions.

Base URL

https://app.screendesk.io/api/v2/scim/

Welcome to the Screendesk API! You can use this API to access our endpoints, such as the Screendesk API to get your recordings.

To access our API, you need to be on the Screendesk Enterprise plan.

If you have any questions about the Enterprise plan, you can reach out to the Sales team.

All responses from the API will include a standard HTTP successful or error status code. The successful status codes are as follows:

For errors, we include extra information as to why the request was not successful. The error response body will have the following format:

{
  "error": {
    "message": "Descriptive information about the error",
    "code": "HTTP error code",
   }
}

For example, if you try to retrieve a recording that does not exist, you will get the following error response:

{
  "error": {
     "message": "Recording not found or does not exist",
     "code": 404,
   }
}

The error status codes, along with their error types, are as follows:

List Users

Retrieves a list of all users for the current account.

• URL: /Users

• Method: GET

• Response:

  • Code: 200 OK

  • Content:

    Copy

    {
      "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
      "totalResults": <integer>,
      "Resources": [
        {
          "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
          "id": "<string>",
          "userName": "<string>",
          "name": {
            "formatted": "<string>",
            "givenName": "<string>",
            "familyName": "<string>"
          },
          "emails": [
            {
              "primary": true,
              "value": "<string>",
              "type": "work"
            }
          ],
          "active": <boolean>,
          "roles": [<string>]
        },
        // ... more users
      ]
    }

Get User

Retrieves a specific user by their SCIM ID or external ID.

• URL: /Users/:id

• Method: GET

• URL Parameters: id=[string] (SCIM ID or external ID)

• Response:

  • Code: 200 OK

  • Content: Same as individual user object in List Users response

Create User

Creates a new user in the system.

• URL: /Users

• Method: POST

• Data Params:

  Copy

  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "<string>"
    "userName": "<string>",
    "name": {
      "givenName": "<string>",
      "familyName": "<string>"
    },
    "emails": [
      {
        "value": "<string>",
        "primary": true,
        "type": "work"
      }
    ],
    "externalId": "<string>",
    "active": <boolean>,
    "roles": {
      "admin": <boolean>,
      "member": <boolean>,
      "editor": <boolean>
    }
  }

• Response:

  • Code: 201 Created

  • Content: Created user object

Update User

Updates an existing user's information.

• URL: /Users/:id (SCIM ID or external ID)

• Method: PUT

• URL Parameters: id=[string] ( ID or external ID)

• Data Params: Same as Create User

• Response:

  • Code: 200 OK

  • Content: Updated user object

5. Delete User

Deletes a user from the system.

• URL: /Users/:id

• Method: DELETE

• URL Parameters: id=[string] ( ID or external ID)

• Response:

  • Code: 204 No Content

Error Responses

In case of errors, the API will respond with an appropriate HTTP status code and a JSON object containing error details:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail": "<string>",
  "status": "400"
}

Common error scenarios:

• User not found: 404 Not Found

• Invalid input: 422 Unprocessable Entity

• Attempting to delete account owner: 403 Forbidden

• Internal server error: 500 Internal Server Error

Notes

• The API uses SCIM 2.0 schemas and conventions.

• User passwords are automatically generated and not returned in responses.

• The active field in user objects indicates whether the user account is currently active.

• The roles field in user objects contains an object with role names as keys and boolean values indicating whether the role is assigned to the user within the current account.

Overriding Roles

When creating or updating a user, you can override the default roles by including a roles object in your request. The roles object should contain boolean values for each role you want to set:

"roles": {
  "admin": false,
  "member": true,
  "editor": false
}

• If you don't include the roles object, the default roles will be applied (admin: false, member: true, editor: false).

• If you include the roles object but omit a role, it will be set to false by default.

• To assign a role to a user, set its value to true in the roles object.

• To remove a role from a user, set its value to false in the roles object.

Example:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "john.doe@example.com",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "emails": [
    {
      "value": "john.doe@example.com",
      "primary": true,
      "type": "work"
    }
  ],
  "active": true,
  "roles": {
    "admin": true,
    "member": true,
    "editor": false
  }
}

This request would create a user with both admin and member roles, but without the editor role.

• When creating or updating users, email validation is skipped to accommodate various SCIM client behaviors.

• The account owner cannot be deleted through this API.