Opti ID SCIM REST APIs

  • Updated
SCIM provisioning for Opti ID is in beta.

The Opti ID SCIM service provider is a multi-tenant service. Every operation is done in the context of the requesting organization. For example, if the operation is to get all users, then the request returns only the users for the organization making the request.

Optimizely is working on the full implementation of these APIs. The current SCIM RFC compliance is noted for each endpoint.

To view the Swagger definitions for these endpoints, see Optimizely Identity SCIM APIs.

Groups endpoints

Query for SCIM groups (GET)

  • API path/scim/v2/groups
  • Opti ID expected behavior and implementation

    Returns all groups for the requesting organization. The SCIM RFC defines filtering parameters to narrow the results and the returned attributes in each group, but currently, Optimizely only supports returning all attributes for each group with pagination.

    Currently, only the following filters are supported:

    • pagination
    • attribute value eq operator on the displayName attribute
  • Error conditions
    • 400 (Bad Request) – If the request contains a filter operator that Opti ID does not support. 
  • SCIM RFC compliance

    The optional filter parameter is not fully implemented, and if you specify a non-supported filter operator, then a bad response is returned. Only the eq operator is implemented against the supported group schema attributes.

    • The required attributes parameter is not implemented.
    • The optional sort parameters are not implemented.
    • The pagination parameters are supported.
    • Querying with POST or .search is not supported.

Add a SCIM group (POST)

  • API path/scim/v2/groups
  • API payload
    {
      "externalId": "${__UUID}",
      "displayName": "{{display-name}}",
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "members": []
    }
  • Opti ID expected behavior and implementation

    Adds a group to the organization. The created group with its attributes is returned to the client. The supported attributes are:

    • displayName – Mapped to the display name of the group.

    • members – The users inside the group.
  • Error conditions
    • 409 (Conflict) – If the group display name is system group or the group display name exists.
  • SCIM RFC compliance

    This endpoint fully complies with the SCIM RFC as it relates to the supported schema.

Get a SCIM group (GET)

  • API path/scim/v2/groups/{id}
  • Parameters
    • {id} – The ID of the group. In Opti ID, this corresponds exactly to the ID attribute value.
  • Opti ID expected behavior and implementation

    Gets the group with the specified ID from the organization. The group is returned with its supported attributes.

  • Error conditions
    • 404 (Not Found) – If a group with the specified ID is not found.
  • SCIM RFC compliance

    This endpoint fully complies with the SCIM RFC as it relates to the supported schema.

Modify a SCIM group by identifier (PATCH)

  • API path/scim/v2/groups/{id}
  • Parameters
    • {id} – The ID of the group. In Opti ID, this corresponds exactly to the ID attribute value.
  • API payload
    {
        "schemas": [
            "urn:ietf:params:scim:api:messages:2.0:PatchOp"
        ],
        "Operations": [
            {
                "name": "addMember",
                "op": "add",
                "path": "members",
                "value": [
                  {
                  "displayName":"new user",
                  "value":"{{user-id}}"
                  }
                ]            
          },
            {
                "op": "remove",
              "path": "members[value eq \"{{user-id}}\"]"
            }
        ]
    }
    Other flavors of the payload are supported as well. For example, a replace operation without a path where the value implies the attribute path and its value.
  • Opti ID expected behavior and implementation

    The patch group endpoint selectively modifies the attributes of the group indicated by the ID parameter. You can add or remove the value for the following attribute:

    • members – The users inside the group.

  • Error conditions
    • 404 (Not Found) – If a group with the specified ID is not found.
    • 400 (Bad Request) – If the patch operation syntax is invalid or Opti ID does not support the patch operation.
  • SCIM RFC compliance

    Aside from the notes in the expected behavior, this endpoint otherwise fully complies with the SCIM RFC as it relates to the supported schema.

Update a SCIM group by identifier (PUT)

  • API path/scim/v2/groups/{id}
  • Parameters
    • {id} – The ID of the group. In Opti ID, this corresponds exactly to the ID attribute value.
  • API payload
    {
       "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
       "id":"{{group-id}}",
       "displayName": "{{display-name}}",
        "members":[
            {
              "value": "{{user1}}",
              "display":"user name 1"
            },
            {
              "value":"{{user2}}",
              "display":"user name 2"
            }
        ]
    }
  • Opti ID expected behavior and implementation

    Updates a group in the organization. The updated group with its attributes is returned to the client. You can update the value for the following attributes:

    • members – The users inside the group.
    • DisplayName – The display name of the group.

    You cannot update the value for the following attributes:

    • id – Mapped to the identifier of the group.
  • Error conditions
    • 404 (Not Found) – If a group with the specified ID is not found.
  • SCIM RFC compliance

    This endpoint fully complies with the SCIM RFC as it relates to the supported schema.

Delete SCIM group by identifier (DELETE)

  • API path/scim/v2/groups/{id}
  • Parameters
    • {id} – The ID of the group. In Opti ID, this corresponds exactly to the ID attribute value.
  • Opti ID expected behavior and implementation

    Permanently removes the group and any access the group had in Opti ID at the time of deletion.

  • Error conditions
    • None
  • SCIM RFC compliance

    This endpoint fully complies with the SCIM RFC as it relates to the supported schema.

Users endpoints

Query for SCIM users (GET)

  • API path/scim/v2/users
  • Opti ID expected behavior and implementation

    Returns all users for the requesting organization. The SCIM RFC defines filtering parameters to narrow the results and control the returned attributes in each user. Currently, Optimizely only supports the following filters:

    • pagination
    • attribute value eq operator on the username, name.givenName, and name.familyName attributes
  • Error conditions
    • 400 (Bad Request) – If the request contains a filter operator Opti ID does not support.
  • SCIM RFC compliance

    The optional filter parameter is not fully implemented, and if you specify a non-supported filter operator, then a bad response is returned. Only the eq operator is implemented against the supported user schema attributes.

    • The required attributes parameter is not implemented.
    • The optional sort parameters are not implemented.
    • The pagination parameters are supported.
    • Querying with POST or .search is not supported.

Add a SCIM user (POST)

  • API path/scim/v2/users
  • API payload
    {
      "UserName": "{{email}}",
        "Active": true,
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "externalId": "${__UUID}",
        "name": {
          "familyName": "{{last-name}}",
          "givenName": "{{first-name}}"
        }
    }
  • Opti ID expected behavior and implementation

    Adds a user to the organization. The created user with its attributes is returned to the client. The supported attributes are:

    • userName – Mapped to the email of the user.
    • active – In a POST, the active setting is ignored and is assumed to be true.
    • name.familyName – The last name of the user.
    • name.givenName – The first name of the user.
  • Error conditions
    • 409 (Conflict) – If a user with the same email address or user name already exists in the SCIM organization or any other organization.
  • SCIM RFC compliance

    This endpoint fully complies with the SCIM RFC as it relates to the supported schema.

Get a SCIM user (GET)

  • API path/scim/v2/users/{id}
  • Parameters
    • {id} – The ID of the user. In Opti ID, this corresponds exactly to the userName attribute value.
  • Opti ID expected behavior and implementation

    Gets the user with the specified ID from the organization. The user is returned with its supported attributes.

  • Error conditions
    •  404 (Not Found) – If a user with the specified ID is not found.
  • SCIM RFC compliance

    This endpoint fully complies with the SCIM RFC as it relates to the supported schema.

Update SCIM user by identifier (PUT)

  • API path/scim/v2/users/{id}
  • Parameters
    • {id} – The ID of the user. In Opti ID, this corresponds exactly to the userName attribute value.
  • API payload
    {
      "UserName": "{{email}}",
      "Active": true | false,
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "externalId": "${__UUID}",
        "name": {
          "familyName": "{{last-name}}",
          "givenName": "{{first-name}}"
        }
    }
  • Opti ID expected behavior and implementation

    Updates a user in the organization. The updated user with its attributes is returned to the client. You can update the value for the following attributes:

    • name.familyName – The last name of the user.
    • name.givenName – The first name of the user.

    You cannot update the value for the following attributes:

    • userName – Mapped to the email of the user.

    If you send the active attribute in the payload with: 

    • a value of false, the user is permanently deleted from Opti ID.
    • a value of true, it does not affect the outcome of the operation.
  • Error conditions
    •  404 (Not Found) – If a user with the specified ID is not found.
  • SCIM RFC compliance

    Aside from the notes captured in the expected behavior, this endpoint otherwise fully complies with the SCIM RFC as it relates to the supported schema.

Modify SCIM user by identifier (PATCH)

  • API path/scim/v2/users/{id}
  • Parameters
    • {id} – The ID of the user. In Opti ID, this corresponds exactly to the userName attribute value.
  • API payload
    {
        "schemas": [
            "urn:ietf:params:scim:api:messages:2.0:PatchOp"
        ],
        "Operations": [
            {
                "op": "replace",
                "path": "name.givenName",
                "value": "ryan3"
            }
        ]
    }
    Other flavors of the payload are supported as well. For example, a replace operation without a path where the value implies the attribute path and its value.
  • Opti ID expected behavior and implementation

    The patch user endpoint selectively modifies the attributes of the user indicated by the ID parameter. You can replace (but not add or remove) the values for the following attributes:

    • name.familyName – The last name of the user.
    • name.givenName – The first name of the user.

    You cannot replace, add, or remove the values for the following attributes:

    • userName – Mapped to the email of the user.

    If you send the active attribute in the payload with a value of false, the user is permanently deleted from Opti ID.

  • Error conditions
    • 404 (Not Found) – If a user with the specified ID is not found.
    • 400 (Bad Request) – If the patch operation syntax is invalid or Opti ID does not support the patch operation.
  • SCIM RFC compliance

    Aside from the notes in the expected behavior, this endpoint otherwise fully complies with the SCIM RFC as it relates to the supported schema. Except for complex paths are not supported, like the following examples:

    • "path":"addresses[type eq \"work\"]"
    • "path":"members[value eq \"2819c223-7f76-453a-919d-413861904646\"].displayName"

Delete SCIM user by identifier (DELETE)

  • API path/scim/v2/users/{id}
  • Parameters
    • {id} – The ID of the user. In Opti ID, this corresponds exactly to the userName attribute value.
  • Opti ID expected behavior and implementation

    Permanently removes the user and any access the user had in Opti ID at the time of deletion.

  • Error conditions
    • None
  • SCIM RFC compliance

    This endpoint fully complies with the SCIM RFC as it relates to the supported schema.