> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/api/readme/scim.md). # SCIM Use these operations to interact with [SCIM-provisioned users](/configure/settings/managing-users/provisioning-users-with-scim/okta-scim.md) in Cortex. ### Required permissions * Your API key must have the `Configure Open ID Connector & SCIM` permission. ### Required SCIM toggles Each operation is gated on the matching SCIM toggle in your [workspace settings](https://app.getcortexapp.com/settings/scim). A request whose required toggle is off is rejected without taking effect: | Operation | Required toggle | Response when the toggle is off | | --------------------------------------------------------- | ---------------------------------------- | ------------------------------- | | Create user (`POST /scim/v2/Users`) | Enable automatic provisioning of users | `403` | | Delete user (`DELETE /scim/v2/Users/{id}`) | Enable automatic deprovisioning of users | `403` | | Get user, Find users (`GET`) | Any SCIM toggle enabled | `403` | | Update or patch that deactivates a user (`active: false`) | Enable automatic deprovisioning of users | `400` | | Update or patch that reactivates a user (`active: true`) | Enable automatic provisioning of users | `400` | | Update or patch of other user attributes | Any SCIM toggle enabled | `400` | A user created or reactivated while automatic provisioning is enabled is always assigned your workspace's default role. ## Operations {% hint style="info" %} For the filter string in the `Find users` operation, use a value of `userName eq ""` to return a result based on an email value. {% endhint %} ## Find users > Fetches users based on provided criteria ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"SCIM"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}},"schemas":{"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}}},"paths":{"/scim/v2/Users":{"get":{"description":"Fetches users based on provided criteria","operationId":"findUsers","parameters":[{"in":"query","name":"attributes","required":false,"schema":{"type":"string"}},{"in":"query","name":"excludedAttributes","required":false,"schema":{"type":"string"}},{"in":"query","name":"filter","required":false,"schema":{"type":"string"}},{"in":"query","name":"startIndex","required":false,"schema":{"type":"integer","format":"int32"}},{"in":"query","name":"count","required":false,"schema":{"type":"integer","format":"int32"}},{"in":"query","name":"sortBy","required":false,"schema":{"type":"string"}},{"in":"query","name":"sortOrder","required":false,"schema":{"type":"string"}},{"in":"query","name":"domain","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}},"description":"Returns list of requested users"},"403":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}},"description":"All SCIM operations are disabled"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Find users","tags":["SCIM"]}}}} ``` ## Gets a user by id > Gets a user based on provided id ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"SCIM"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}},"schemas":{"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}}},"paths":{"/scim/v2/Users/{id}":{"get":{"description":"Gets a user based on provided id","operationId":"getUser","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"attributes","required":false,"schema":{"type":"string"}},{"in":"query","name":"excludedAttributes","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}},"description":"Returns requested user data"},"403":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}},"description":"All SCIM operations are disabled"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Gets a user by id","tags":["SCIM"]}}}} ``` ## Creates a user > Creates a user based on provided data. ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"SCIM"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}},"schemas":{"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}}},"paths":{"/scim/v2/Users":{"post":{"description":"Creates a user based on provided data.","operationId":"createUser","parameters":[{"in":"query","name":"attributes","required":false,"schema":{"type":"string"}},{"in":"query","name":"excludedAttributes","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}},"description":"Returns created user data"},"403":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}},"description":"Automatic provisioning of users is disabled"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Creates a user","tags":["SCIM"]}}}} ``` ## Updates a user > Updates a user based on provided id and data ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"SCIM"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}},"schemas":{"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}}},"paths":{"/scim/v2/Users/{id}":{"put":{"description":"Updates a user based on provided id and data","operationId":"updateUser","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"attributes","required":false,"schema":{"type":"string"}},{"in":"query","name":"excludedAttributes","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}},"description":"Returns updated user data"},"400":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}},"description":"The SCIM toggle required for the requested change is disabled (provisioning for reactivation, deprovisioning for deactivation)"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Updates a user","tags":["SCIM"]}}}} ``` ## Patches a user > Replaces user details based on provided id and data ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"SCIM"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}},"schemas":{"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}}},"paths":{"/scim/v2/Users/{id}":{"patch":{"description":"Replaces user details based on provided id and data","operationId":"patchUser","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"attributes","required":false,"schema":{"type":"string"}},{"in":"query","name":"excludedAttributes","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}},"description":"Returns patched user data"},"400":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}},"description":"The SCIM toggle required for the requested change is disabled (provisioning for reactivation, deprovisioning for deactivation)"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Patches a user","tags":["SCIM"]}}}} ``` ## Deletes a user > Deletes a user based on provided id ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"SCIM"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}},"schemas":{"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}}},"paths":{"/scim/v2/Users/{id}":{"delete":{"description":"Deletes a user based on provided id","operationId":"deleteUser","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}},"description":"Returns deleted user data"},"403":{"content":{"application/json":{"schema":{"type":"string"}},"application/scim+json":{"schema":{"type":"string"}}},"description":"Automatic deprovisioning of users is disabled"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Deletes a user","tags":["SCIM"]}}}} ```