Identity Gateway (1.0.0)

Download OpenAPI specification:Download

E-mail: moveworks-gateway@moveworks.ai

Any customer looking forward to build, manage and host their own identity source can accomplish it by hosting an identity gateway that implements Moveworks API specification for identity sources provided below. This will enable them to have greater control and flexibility over what attributes they are able to federate into Moveworks User objects.

For ingestion, Moveworks exclusively includes active users and does not process inactive users. In simple words mark a user as active(state: ACTIVE) if they are to be ingested otherwise mark them as inactive(state: INACTIVE)

By default, the full sync method is used for ingestion. However, if a customer prefers the incremental sync approach for its advantages, they must opt for soft deletion. This means that user records are marked as inactive instead of being completely removed from the database when deleted. In cases where hard deletion occurs in the database, the default approach reverts to full sync. Additionally, to support incremental sync, the identity gateway must maintain a "last_updated_at" attribute for each user and update it whenever the user is modified.

We will share more information on how to convey your deletion approach(soft or hard deletion) to us once we start supporting incremental sync.

List Users

List of users should be returned from this API in a deterministic order. Deterministic order is desired if we decide to use pagination. Anticipated load – Moveworks will call this endpoint to ingest users, polling would be as frequent as every 4 hours, could be even more aggressive in extenuating circumstances and it could be as seldom as 2 weeks. We recommend a rate limit of 10 req/sec for this endpoint.

SecuritybearerAuth
Request
query Parameters
pageToken
string

Used to paginate query results, determining starting point for the next page of records retrieval. When a query operation returns a large number of results surpassing the specified page size, the gateway is expected to restrict the response size to the provided page size. It should automatically include a "next_page_token" field in the response. To obtain the subsequent page of results, the client will employ the "pageToken" and set it to the value of the "next_page_token" in the following request. This approach facilitates the efficient retrieval of large result sets through multiple paginated requests. Since this parameter value becomes available starting from the second call, it will be omitted during the initial call to retrieve records.

When combining the filter parameter with the pageToken parameter, servers must ensure that the client uses the appropriate pageToken value for the specified filter string. Failure to do so should result in the server throwing an "INPUT_VALIDATION_FAILED".

pageSize
integer <int64>

Maximum number of users to return in a single query. Defaults to 1000.

Note: Server is free to return less number of users.

filter
string

Defines a filter expression that narrows down the returned set of items. It allows you to specify criteria, such as numeric comparisons or string matching, to filter the items based on the values of their properties.

The filter parameter must include at least one valid Boolean expression. Each expression should consist of an attribute name, followed by an attribute operator and a value. You have the flexibility to combine multiple expressions using logical operators, and you can also group expressions together using parentheses “()”.

Here are the available attribute operators and their descriptions:

  • eq (equal): The attribute and operator values must be identical for a match.
  • ne (not equal): The attribute and operator values are not identical.
  • gt (greater than): If the attribute value is greater than the operator value, there is a match. The actual comparison depends on the attribute type.
  • lt (less than): If the attribute value is less than the operator value, there is a match. The actual comparison depends on the attribute type.

The boolean operators available for combining expressions are:

  • and (Logical AND): The filter is considered a match only if both expressions evaluate to true.
  • or (Logical OR): The filter is considered a match if either of the expressions evaluates to true.

Parentheses () can be used to group boolean expressions and alter the standard order of operations. By grouping expressions with parentheses, you can control how the logical OR operation is evaluated and prioritize certain conditions over others. This allows for more flexibility and precision in constructing complex boolean expressions.

Attribute names and attribute operators used in filters are case insensitive. For example, the following two expressions will evaluate to the same logical value: filter=user.state Eq "ACTIVE" filter=user.STate eq "ACTIVE"

The evaluation of filters follows a standard order of operations. Attribute operators take precedence over other operators, followed by the grouping operator (parentheses), then the logical AND operator, and finally the logical OR operator.

If the requested filter operation is not recognised, providers must refuse to filter the results and return an HTTP 400 error with an appropriate human readable response.

Here are some examples of filter expressions: In the provided examples, we have utilised the suggested response structure as defined in the response section. However, it's important to note that these expressions may differ if you opt for an alternative response format or structure.

  • filter=last_modified_at gt "2011-05-13T04:42:34Z"
  • filter=user.state ne “INACTIVE” and last_modified_at gt "2011-05-13T04:42:34Z"
Examples:
During a full sync, Moveworks can retrieve only users in the active state, which restricts the returned results to the desired users for ingestion.
filter=user.state eq "ACTIVE"
During an incremental sync, the query parameter with the "last_modified_at" attribute is utilised to fetch records that have been modified since a specific timestamp.
filter=last_modified_at gt "2022-10-20T17:28:52Z"
In some cases, a customer may have specific requirements for the data that is ingested into Moveworks. For example, they may only want to ingest users who belong to a particular cost center, identified by the cost_center_id attribute. To achieve this, the customer can request that Moveworks includes a filter expression with the value of 'A' for the cost_center_id attribute in every API call made by Moveworks. This will ensure that only users who belong to cost center 'A' are ingested into the Moveworks system.
filter=user.employment_info.cost_center_id eq "A"
Responses
200

List of users

default

There was an error. Please see our error documentation for details on what the errors mean. https://docs.moveworks.ai/gateway/errors/

get/users
Request samples 
Response samples 
application/json
{
  • "results": [
    ],
  • "next_page_token": "ABCD1234"
}
Get User By ID
Returns user details given their userId. We recommend a rate limit of 5 req/sec for this endpoint.


SecuritybearerAuth 
Request 
path Parameters
userId
required
string
ID of user to fetch details for


 
Responses 
200
A single user


default
There was an error. Please see our error documentation for details on what the errors mean. https://docs.moveworks.ai/gateway/errors/


get/users/{userId}
Request samples 
Response samples 
application/json
{
  • "user": {
    },
  • "system_identity": {
    },
  • "last_updated_at": "2023-05-14T09:30:00Z"
}