From ca02ba5ab12662db5dc1935e36d53b47de008f09 Mon Sep 17 00:00:00 2001 From: fflorent Date: Fri, 11 Oct 2024 12:48:04 +0200 Subject: [PATCH 01/10] Document SCIM for users (WIP) --- api/grist.yml | 13 +- api/scim/bulk.yml | 47 ++++ api/scim/serviceproviderconfig.yml | 279 +++++++++++++++++++++ api/scim/users.yml | 386 +++++++++++++++++++++++++++++ help/en/docs/api.md | 122 ++++++++- 5 files changed, 843 insertions(+), 4 deletions(-) create mode 100644 api/scim/bulk.yml create mode 100644 api/scim/serviceproviderconfig.yml create mode 100644 api/scim/users.yml diff --git a/api/grist.yml b/api/grist.yml index 4d28bf9a4..8ab286dbc 100644 --- a/api/grist.yml +++ b/api/grist.yml @@ -10,7 +10,7 @@ openapi: 3.0.0 security: - ApiKey: [] servers: - - url: https://{subdomain}.getgrist.com/api + - url: https://{gristhost}/api variables: subdomain: description: The team name, or `docs` for personal areas @@ -1151,6 +1151,14 @@ paths: description: "The caller is not allowed to delete this account" 404: description: "The user is not found" + /scim/v2/Users: + $ref: "./scim/users.yml#/paths/~1scim~1v2~1Users" + /scim/v2/Users/{userId}: + $ref: "./scim/users.yml#/paths/~1scim~1v2~1Users~1{userId}" + /scim/v2/Users/.search: + $ref: "./scim/users.yml#/paths/~1scim~1v2~1Users~1.search" + /scim/v2/Bulk/: + $ref: "./scim/bulk.yml#/paths/~1scim~1v2~1Bulk" tags: - name: orgs @@ -1175,6 +1183,8 @@ tags: description: "Sql endpoint to query data from documents." - name: users description: "Grist users." + - name: scim + description: "SCIM" components: securitySchemes: ApiKey: @@ -2199,3 +2209,4 @@ components: - label description: "Format for headers. Labels tend to be more human-friendly while colIds are more normalized." required: false + diff --git a/api/scim/bulk.yml b/api/scim/bulk.yml new file mode 100644 index 000000000..ff74d54c7 --- /dev/null +++ b/api/scim/bulk.yml @@ -0,0 +1,47 @@ +paths: + /scim/v2/Bulk: + post: + summary: Bulk operation + operationId: bulkOperation + tags: + - scim + requestBody: + description: Operations to be performed in bulk. + required: true + content: + application/scim+json: + schema: + type: object + properties: + schemas: + type: array + items: + type: string + enum: + - "urn:ietf:params:scim:api:messages:2.0:BulkRequest" + Operations: + type: array + description: List of operations to be executed. + items: + type: object + properties: + method: + type: string + description: HTTP method for the operation. + example: "POST" + path: + type: string + description: Resource path for the operation. + example: "/scim/v2/Users" + data: + type: object + description: Data for the operation. + responses: + '200': + description: Bulk operations executed successfully. + '400': + description: Bad request. + '500': + description: Internal server error. + + diff --git a/api/scim/serviceproviderconfig.yml b/api/scim/serviceproviderconfig.yml new file mode 100644 index 000000000..03e56da8a --- /dev/null +++ b/api/scim/serviceproviderconfig.yml @@ -0,0 +1,279 @@ +paths: + /scim/v2/Schemas: + get: + summary: Retrieve SCIM schemas + operationId: getSchemas + tags: + - Schemas + responses: + '200': + description: Successfully retrieved schemas. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Schema' + '500': + description: Internal server error. + + /scim/v2/ServiceProviderConfig: + get: + summary: Retrieve service provider configuration + operationId: getServiceProviderConfig + tags: + - ServiceProviderConfig + responses: + '200': + description: Successfully retrieved service provider configuration. + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceProviderConfig' + '500': + description: Internal server error. + + /scim/v2/ResourceTypes: + get: + summary: Retrieve SCIM resource types + operationId: getResourceTypes + tags: + - ResourceTypes + responses: + '200': + description: Successfully retrieved resource types. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ResourceType' + '500': + description: Internal + + +components: + schemas: + User: + type: object + properties: + id: + type: string + description: The unique identifier of the user. + example: "e9e30dba-f08f-4109-8486-d5c6a331660a" + userName: + type: string + description: The unique username. + example: "john.doe@example.com" + name: + type: object + properties: + formatted: + type: string + description: Full name of the user. + example: "John Doe" + emails: + type: array + items: + type: object + properties: + value: + type: string + description: The user's email address. + example: "john.doe@example.com" + primary: + type: boolean + description: Whether this is the primary email. + example: true + + ResourceType: + type: object + description: Describes the SCIM resource types supported by the service provider. + properties: + id: + type: string + description: Unique identifier for the resource type. + example: "User" + name: + type: string + description: Name of the resource type. + example: "User" + description: + type: string + description: Human-readable description of the resource type. + example: "Top-level resource representing a user." + endpoint: + type: string + description: The relative URL of the resource type's endpoint. + example: "/scim/v2/Users" + schema: + type: string + description: The primary schema URI for the resource type. + example: "urn:ietf:params:scim:schemas:core:2.0:User" + schemaExtensions: + type: array + description: Optional schema extensions. + items: + type: object + properties: + schema: + type: string + description: The URI of the extended schema. + example: "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" + required: + type: boolean + description: Whether the schema extension is required. + example: false + + ServiceProviderConfig: + type: object + description: Represents the service provider's SCIM configuration. + properties: + documentationUri: + type: string + description: URL to the service provider’s documentation. + example: "https://api.example.com/scim/docs" + patch: + type: object + description: Configuration related to PATCH operations. + properties: + supported: + type: boolean + description: Indicates whether the PATCH operation is supported. + example: true + bulk: + type: object + description: Configuration related to bulk operations. + properties: + supported: + type: boolean + description: Indicates whether the bulk operation is supported. + example: true + maxOperations: + type: integer + description: The maximum number of operations allowed in a bulk request. + example: 1000 + maxPayloadSize: + type: integer + description: The maximum payload size for a bulk request. + example: 1048576 + filter: + type: object + description: Configuration related to filtering. + properties: + supported: + type: boolean + description: Indicates whether filtering is supported. + example: true + maxResults: + type: integer + description: The maximum number of results that can be returned by a single query. + example: 100 + changePassword: + type: object + description: Configuration related to password changes. + properties: + supported: + type: boolean + description: Indicates whether the password change operation is supported. + example: false + sort: + type: object + description: Configuration related to sorting. + properties: + supported: + type: boolean + description: Indicates whether sorting is supported. + example: true + etag: + type: object + description: Configuration related to ETag versioning. + properties: + supported: + type: boolean + description: Indicates whether ETag versioning is supported. + example: false + authenticationSchemes: + type: array + description: Supported authentication schemes. + items: + type: object + properties: + name: + type: string + description: Name of the authentication scheme. + example: "OAuth Bearer Token" + description: + type: string + description: Description of the authentication scheme. + example: "Authentication scheme using the OAuth Bearer Token." + specUri: + type: string + description: URI of the authentication specification. + example: "http://tools.ietf.org/html/rfc6750" + type: + type: string + description: The type of the authentication scheme. + example: "oauthbearertoken" + primary: + type: boolean + description: Indicates if this is the primary authentication scheme. + example: true + + Schema: + type: object + description: Describes a SCIM schema resource. + properties: + id: + type: string + description: The unique identifier of the schema. + example: "urn:ietf:params:scim:schemas:core:2.0:User" + name: + type: string + description: Human-readable name of the schema. + example: "User" + description: + type: string + description: Description of the schema. + example: "Schema for representing a user." + attributes: + type: array + description: List of attributes defined in the schema. + items: + type: object + properties: + name: + type: string + description: Name of the attribute. + example: "userName" + type: + type: string + description: Data type of the attribute. + example: "string" + multiValued: + type: boolean + description: Whether the attribute is multi-valued. + example: false + required: + type: boolean + description: Whether the attribute is required. + example: true + canonicalValues: + type: array + description: Canonical values for the attribute, if applicable. + items: + type: string + example: "admin" + mutability: + type: string + description: Defines whether the attribute is readOnly, readWrite, or immutable. + example: "readWrite" + returned: + type: string + description: Specifies when the attribute is returned in a response (always, never, etc.). + example: "default" + uniqueness: + type: string + description: Defines whether the attribute value must be unique. + example: "server" + diff --git a/api/scim/users.yml b/api/scim/users.yml new file mode 100644 index 000000000..44dc1d785 --- /dev/null +++ b/api/scim/users.yml @@ -0,0 +1,386 @@ +paths: + /scim/v2/Users: + get: + summary: Retrieve list of users + operationId: getUsers + tags: + - users + - scim + parameters: + - name: startIndex + in: query + description: The starting index for pagination. + required: false + schema: + type: integer + example: 1 + - name: count + in: query + description: The number of users to retrieve. + required: false + schema: + type: integer + example: 10 + - name: filter + in: query + description: Filter users based on specific criteria. + required: false + schema: + type: string + example: "userName eq 'john.doe'" + responses: + '200': + description: Successfully retrieved list of users. + content: + application/scim+json: + schema: + $ref: "#/components/schemas/UsersListResponse" + '500': + description: Internal server error. + + post: + summary: Create a new user + operationId: createUser + tags: + - users + - scim + requestBody: + description: Data for the user to be created. + required: true + content: + application/scim+json: + schema: + $ref: '#/components/schemas/UserInRequest' + responses: + '201': + description: User created successfully. + content: + application/scim+json: + schema: + $ref: '#/components/schemas/UserInResponse' + '400': + description: Bad request. + '409': + description: Conflict on resource (like email). + '500': + description: Internal server error. + + /scim/v2/Users/{userId}: + get: + summary: Retrieve user by ID + operationId: getUserById + tags: + - users + - scim + parameters: + - $ref: '#/components/parameters/userIdPathParam' + responses: + '200': + description: Successfully retrieved user details. + content: + application/scim+json: + schema: + $ref: '#/components/schemas/UserInResponse' + '404': + description: User not found. + '500': + description: Internal server error. + + put: + summary: Update a user by ID + operationId: updateUserById + tags: + - users + - scim + parameters: + - $ref: '#/params/userIdPathParam' + requestBody: + description: Updated data for the user. + required: true + content: + application/scim+json: + schema: + $ref: '#/components/schemas/UserInRequest' + responses: + '200': + description: User updated successfully. + content: + application/scim+json: + schema: + $ref: '#/components/schemas/UserInResponse' + '400': + description: Bad request. + '404': + description: User not found. + '409': + description: Conflict on resource (like email). + '500': + description: Internal server error. + + patch: + summary: Partially update a user by ID + operationId: patchUserById + tags: + - users + - scim + parameters: + - $ref: '#/params/userIdPathParam' + requestBody: + description: Data for the partial update of the user. + required: true + content: + application/scim+json: + schema: + type: object + properties: + schemas: + type: array + items: + type: string + enum: + - urn:ietf:params:scim:api:messages:2.0:PatchOp + Operations: + type: array + items: + type: object + properties: + op: + type: string + description: Operation type (add, replace, remove). + example: "replace" + path: + type: string + description: The field to be updated. + example: "photos.value" + value: + type: string + description: New value for the field. + example: "https://example.com/pics/john-doe.png" + responses: + '200': + description: User partially updated successfully. + content: + application/scim+json: + schema: + $ref: '#/components/schemas/UserInResponse' + '400': + description: Bad request. + '404': + description: User not found. + '409': + description: Conflict on resource (like email). + '500': + description: Internal server error. + + delete: + summary: Delete a user by ID + operationId: deleteUserById + tags: + - users + - scim + parameters: + - $ref: '#/params/userIdPathParam' + responses: + '204': + description: User deleted successfully. + '404': + description: User not found. + '500': + description: Internal server error. + + /scim/v2/Users/.search: + post: + summary: Search users + operationId: searchUsers + tags: + - users + - scim + requestBody: + description: Search criteria. + required: true + content: + application/scim+json: + schema: + type: object + properties: + schemas: + type: array + items: + type: string + enum: + - "urn:ietf:params:scim:api:messages:2.0:SearchRequest" + filter: + type: string + description: Filter expression for users. + example: "userName eq 'john.doe'" + sortBy: + type: string + description: Field to sort by. + example: "userName" + sortOrder: + type: string + description: Order of sorting (ascending or descending). + example: "ascending" + attributes: + type: array + description: A multi-valued list of strings indicating the names of resource attributes to return in the response. + items: + type: string + example: [ "id", "displayName" ] + excludedAttributes: + type: array + description: A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return. + items: + type: string + example: [ "locale" ] + startIndex: + description: The starting index for pagination. + type: integer + example: 1 + count: + description: The number of users to retrieve. + type: integer + example: 10 + + responses: + '200': + description: Users retrieved based on search criteria. + content: + application/scim+json: + schema: + type: object + properties: + schemas: + type: array + items: + type: string + enum: + - "urn:ietf:params:scim:api:messages:2.0:ListResponse" + totalResults: + type: integer + description: Total number of users found. + Resources: + type: array + items: + $ref: '#/components/schemas/UserInResponse' + '400': + description: Bad request. + '500': + description: Internal server error. + +components: + + params: + userIdPathParam: + in: path + name: userId + schema: + type: integer + description: A user id + required: true + + schemas: + UsersListResponse: + type: object + properties: + schemas: + type: array + items: + type: string + enum: + - "urn:ietf:params:scim:api:messages:2.0:ListResponse" + totalResults: + type: integer + description: Total number of users. + example: 1 + itemsPerPage: + type: integer + description: Number of users returned per page. + example: 20 + startIndex: + type: integer + description: Starting index. + example: 1 + Resources: + type: array + items: + $ref: '#/components/schemas/UserInResponse' + + UserInRequest: + type: object + properties: + schemas: + type: array + items: + type: string + enum: + - "urn:ietf:params:scim:schemas:core:2.0:User" + userName: + type: string + description: The unique username. + example: "john.doe@example.com" + name: + type: object + properties: + formatted: + type: string + description: Full name of the user. + example: "John Doe" + emails: + type: array + items: + type: object + properties: + value: + type: string + description: The user's email address. + example: "john.doe@example.com" + primary: + type: boolean + description: Whether this is the primary email. + example: true + displayName: + type: string + description: the display name of the user + example: "John Doe" + preferredLanguage: + type: string + description: Indicates the user's preferred written or spoken languages and is generally used for selecting a localized user interface. + example: "en" + locale: + type: string + description: Used to indicate the User's default location for purposes of localizing such items as currency, date time format, or numerical representations. + example: "en" + photos: + type: array + description: The picture of the user. It is expected to have a single item in the context of Grist. + items: + type: object + properties: + value: + type: string + description: The picture of the user + example: "https://example.com/pics/john-doe.png" + primary: + type: boolean + description: Whether this is the primary picture + example: true + UserInResponse: + allOf: + - type: object + properties: + meta: + type: object + properties: + resourceType: + type: string + enum: + - "User" + location: + type: string + example: "/api/scim/v2/Users/1" + id: + type: string + description: The unique identifier of the user. + example: "1" + - $ref: '#/components/schemas/UserInRequest' diff --git a/help/en/docs/api.md b/help/en/docs/api.md index 01da6cd98..04a8e313e 100644 --- a/help/en/docs/api.md +++ b/help/en/docs/api.md @@ -58,7 +58,7 @@ REST API for manipulating documents, workspaces, and team sites.
-
API docs by Redocly
API docs by Redocly
400

The passed user name does not match the one retrieved from the database given the passed user id

Request samples

Content type
application/json
{
  • "name": "John Doe"
}
+

Request samples

Content type
application/json
{
  • "name": "John Doe"
}

Retrieve list of users

Authorizations:
ApiKey
query Parameters
startIndex
integer
Example: startIndex=1

The starting index for pagination.

+
count
integer
Example: count=10

The number of users to retrieve.

+
filter
string
Example: filter=userName eq 'john.doe'

Filter users based on specific criteria.

+

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
  • "totalResults": 1,
  • "itemsPerPage": 20,
  • "startIndex": 1,
  • "Resources": [
    • {
      • "schemas": [
        • "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
      • "meta": {
        • "resourceType": "User",
        • "location": "/api/scim/v2/Users/1"
        },
      • "id": "1",
      • "userName": "john.doe@example.com",
      • "name": {
        • "formatted": "John Doe"
        },
      • "emails": [
        • {
          • "value": "john.doe@example.com",
          • "primary": true
          }
        ],
      • "displayName": "John Doe",
      • "preferredLanguage": "en",
      • "locale": "en",
      • "photos": []
      }
    ]
}

Create a new user

Authorizations:
ApiKey
Request Body schema: application/scim+json

Data for the user to be created.

+
schemas
Array of strings
Items Value: "urn:ietf:params:scim:schemas:core:2.0:User"
object
id
string

The unique identifier of the user.

+
userName
string

The unique username.

+
object
Array of objects
displayName
string

the display name of the user

+
preferredLanguage
string

Indicates the user's preferred written or spoken languages and is generally used for selecting a localized user interface.

+
locale
string

Used to indicate the User's default location for purposes of localizing such items as currency, date time format, or numerical representations.

+
Array of objects

The picture of the user. It is expected to have a single item in the context of Grist.

+

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Retrieve user by ID

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

+

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Update a user by ID

Authorizations:
ApiKey
Request Body schema: application/scim+json

Updated data for the user.

+
schemas
Array of strings
Items Value: "urn:ietf:params:scim:schemas:core:2.0:User"
object
id
string

The unique identifier of the user.

+
userName
string

The unique username.

+
object
Array of objects
displayName
string

the display name of the user

+
preferredLanguage
string

Indicates the user's preferred written or spoken languages and is generally used for selecting a localized user interface.

+
locale
string

Used to indicate the User's default location for purposes of localizing such items as currency, date time format, or numerical representations.

+
Array of objects

The picture of the user. It is expected to have a single item in the context of Grist.

+

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Partially update a user by ID

Authorizations:
ApiKey
Request Body schema: application/scim+json

Data for the partial update of the user.

+
op
string

Operation type (add, replace, remove).

+
path
string

The field to be updated.

+
value
string

New value for the field.

+

Responses

Request samples

Content type
application/scim+json
{
  • "op": "replace",
  • "path": "name.familyName",
  • "value": "Doe"
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Delete a user by ID

Authorizations:
ApiKey

Responses

Search users

Authorizations:
ApiKey
Request Body schema: application/scim+json

Search criteria.

+
schemas
Array of strings
Items Value: "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
filter
string

Filter expression for users.

+
sortBy
string

Field to sort by.

+
sortOrder
string

Order of sorting (ascending or descending).

+
attributes
Array of strings

A multi-valued list of strings indicating the names of resource attributes to return in the response.

+
excludedAttributes
Array of strings

A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return.

+
startIndex
integer

The starting index for pagination.

+
count
integer

The number of users to retrieve.

+

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
    ],
  • "filter": "userName eq 'john.doe'",
  • "sortBy": "userName",
  • "sortOrder": "ascending",
  • "attributes": [
    • "id",
    • "displayName"
    ],
  • "excludedAttributes": [
    • "locale"
    ],
  • "startIndex": 1,
  • "count": 10
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
  • "totalResults": 0,
  • "Resources": [
    • {
      • "schemas": [
        • "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
      • "meta": {
        • "resourceType": "User",
        • "location": "/api/scim/v2/Users/1"
        },
      • "id": "1",
      • "userName": "john.doe@example.com",
      • "name": {
        • "formatted": "John Doe"
        },
      • "emails": [
        • {
          • "value": "john.doe@example.com",
          • "primary": true
          }
        ],
      • "displayName": "John Doe",
      • "preferredLanguage": "en",
      • "locale": "en",
      • "photos": []
      }
    ]
}

scim

SCIM

+

Retrieve list of users

Authorizations:
ApiKey
query Parameters
startIndex
integer
Example: startIndex=1

The starting index for pagination.

+
count
integer
Example: count=10

The number of users to retrieve.

+
filter
string
Example: filter=userName eq 'john.doe'

Filter users based on specific criteria.

+

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
  • "totalResults": 1,
  • "itemsPerPage": 20,
  • "startIndex": 1,
  • "Resources": [
    • {
      • "schemas": [
        • "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
      • "meta": {
        • "resourceType": "User",
        • "location": "/api/scim/v2/Users/1"
        },
      • "id": "1",
      • "userName": "john.doe@example.com",
      • "name": {
        • "formatted": "John Doe"
        },
      • "emails": [
        • {
          • "value": "john.doe@example.com",
          • "primary": true
          }
        ],
      • "displayName": "John Doe",
      • "preferredLanguage": "en",
      • "locale": "en",
      • "photos": []
      }
    ]
}

Create a new user

Authorizations:
ApiKey
Request Body schema: application/scim+json

Data for the user to be created.

+
schemas
Array of strings
Items Value: "urn:ietf:params:scim:schemas:core:2.0:User"
object
id
string

The unique identifier of the user.

+
userName
string

The unique username.

+
object
Array of objects
displayName
string

the display name of the user

+
preferredLanguage
string

Indicates the user's preferred written or spoken languages and is generally used for selecting a localized user interface.

+
locale
string

Used to indicate the User's default location for purposes of localizing such items as currency, date time format, or numerical representations.

+
Array of objects

The picture of the user. It is expected to have a single item in the context of Grist.

+

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Retrieve user by ID

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

+

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Update a user by ID

Authorizations:
ApiKey
Request Body schema: application/scim+json

Updated data for the user.

+
schemas
Array of strings
Items Value: "urn:ietf:params:scim:schemas:core:2.0:User"
object
id
string

The unique identifier of the user.

+
userName
string

The unique username.

+
object
Array of objects
displayName
string

the display name of the user

+
preferredLanguage
string

Indicates the user's preferred written or spoken languages and is generally used for selecting a localized user interface.

+
locale
string

Used to indicate the User's default location for purposes of localizing such items as currency, date time format, or numerical representations.

+
Array of objects

The picture of the user. It is expected to have a single item in the context of Grist.

+

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Partially update a user by ID

Authorizations:
ApiKey
Request Body schema: application/scim+json

Data for the partial update of the user.

+
op
string

Operation type (add, replace, remove).

+
path
string

The field to be updated.

+
value
string

New value for the field.

+

Responses

Request samples

Content type
application/scim+json
{
  • "op": "replace",
  • "path": "name.familyName",
  • "value": "Doe"
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Delete a user by ID

Authorizations:
ApiKey

Responses

Search users

Authorizations:
ApiKey
Request Body schema: application/scim+json

Search criteria.

+
schemas
Array of strings
Items Value: "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
filter
string

Filter expression for users.

+
sortBy
string

Field to sort by.

+
sortOrder
string

Order of sorting (ascending or descending).

+
attributes
Array of strings

A multi-valued list of strings indicating the names of resource attributes to return in the response.

+
excludedAttributes
Array of strings

A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return.

+
startIndex
integer

The starting index for pagination.

+
count
integer

The number of users to retrieve.

+

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
    ],
  • "filter": "userName eq 'john.doe'",
  • "sortBy": "userName",
  • "sortOrder": "ascending",
  • "attributes": [
    • "id",
    • "displayName"
    ],
  • "excludedAttributes": [
    • "locale"
    ],
  • "startIndex": 1,
  • "count": 10
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
  • "totalResults": 0,
  • "Resources": [
    • {
      • "schemas": [
        • "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
      • "meta": {
        • "resourceType": "User",
        • "location": "/api/scim/v2/Users/1"
        },
      • "id": "1",
      • "userName": "john.doe@example.com",
      • "name": {
        • "formatted": "John Doe"
        },
      • "emails": [
        • {
          • "value": "john.doe@example.com",
          • "primary": true
          }
        ],
      • "displayName": "John Doe",
      • "preferredLanguage": "en",
      • "locale": "en",
      • "photos": []
      }
    ]
}

Bulk operation

Authorizations:
ApiKey
Request Body schema: application/scim+json

Operations to be performed in bulk.

+
schemas
Array of strings
Items Value: "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
Array of objects

List of operations to be executed.

+

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
    ],
  • "Operations": [
    • {
      • "method": "POST",
      • "path": "/scim/v2/Users",
      • "data": { }
      }
    ]
}