> For the complete documentation index, see [llms.txt](https://docs.riskbase.uk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.riskbase.uk/riskbase-docs/scim/users.md).

# Users

## List Users

> Returns a paginated list of users

```json
{"openapi":"3.1.1","info":{"title":"RiskBase SCIM Version 2.0","version":"0.0.1"},"tags":[{"name":"Users","description":""}],"servers":[{"url":"https://api3.riskbase.uk/sso/{organisationId}/scim/v2"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/Users":{"get":{"tags":["Users"],"summary":"List Users","description":"Returns a paginated list of users","parameters":[{"schema":{"type":"string","description":"The following filters are available:\n\n- `id` with comparison operators `eq` `co` `sw` `ew`\n- `userName` with comparison operators `eq` `co` `sw` `ew`\n- `name.familyName` with comparison operators `eq` `co` `sw` `ew`\n- `name.givenName` with comparison operators `eq` `co` `sw` `ew`\n- `email` with comparison operators `eq` `co` `sw` `ew`\n- `active` with comparison operators `eq`\n\nMultiple filters can be used with the logical operators `and` `or`\n"},"in":"query","name":"filter"},{"schema":{"type":"integer","default":1},"in":"query","name":"startIndex","description":"Index of the first query result"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":500},"in":"query","name":"count","description":"Maximun numer of query results per page"},{"schema":{"type":"string","enum":["userName","email","givenName","familyName"],"default":"userName"},"in":"query","name":"sortBy"},{"schema":{"type":"string","enum":["ascending","descending"],"default":"ascending"},"in":"query","name":"sortOrder"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","enum":["urn:ietf:params:scim:api:messages:2.0:ListResponse"]},"totalResults":{"type":"int"},"startIndex":{"type":"int"},"itemsPerPage":{"type":"int"},"Resources":{"type":"array","items":{"type":"object","properties":{"schemas":{"type":"array","items":{"type":"string","enum":["urn:ietf:params:scim:schemas:core:2.0:User"]}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"active":{"type":"boolean"},"emails":{"type":"array","items":{"type":"object","properties":{"value":{"type":"email"},"type":{"type":"string","enum":["work"]},"primary":{"type":"boolean"}}}},"name":{"type":"object","properties":{"formatted":{"type":"string"},"givenName":{"type":"string"},"familyName":{"type":"string"}}},"authenticationType":{"type":"enum","enum":["saml","passwordless"]},"roles":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"}}}},"meta":{"type":"object","properties":{"resourceType":{"type":"string","enum":["User"]},"created":{"type":"string"},"lastModified":{"type":"string"},"location":{"type":"string"}}}}}}}}}}},"400":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array"},"scimType":{"type":"string","enum":["invalidFilter"]},"detail":{"type":"string","enum":["Invalid filter"]},"status":{"type":"int","enum":[400]}}}}}}}}}}}
```

## Create User

> The POST request is used to create a new user.<br>

```json
{"openapi":"3.1.1","info":{"title":"RiskBase SCIM Version 2.0","version":"0.0.1"},"tags":[{"name":"Users","description":""}],"servers":[{"url":"https://api3.riskbase.uk/sso/{organisationId}/scim/v2"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/Users":{"post":{"tags":["Users"],"summary":"Create User","description":"The POST request is used to create a new user.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["userName","emails","name"],"properties":{"schemas":{"type":"array"},"userName":{"type":"string","format":"email","required":true,"description":"Your unique immutable ID"},"emails":{"description":"The first email with `primary: true` is used; all other emails are discarded.\nThe first email address is used if no emails have `primary: true`; all other emails are discarded\n","type":"array","items":{"type":"object","properties":{"value":{"type":"email"},"primary":{"type":"boolean"}}}},"name":{"type":"object","properties":{"givenName":{"type":"string","required":true},"familyName":{"type":"string","required":true}}},"authenticationType":{"type":"enum","enum":["saml","passwordless"],"default":"saml","description":"User should sign-in through your own IdP-initiated SAML SSO or directly into RiskBase with a passwordless account.\n\nThis cannot currently be changed once the user has been added. If you'd like to change an existing user's `authenticationType`, please get in touch with support@riskbase.uk\n"},"roles":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"}}}},"active":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"See **Get User**. Store the response's `id` and use this in future requests related to this user."},"400":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","enum":["urn:ietf:params:scim:api:messages:2.0:Error"]},"scimType":{"type":"string","enum":["invalidValue"]},"detail":{"type":"string","enum":["userName must be an email"]},"status":{"type":"int","enum":[400]}}}}}},"409":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","items":{"type":"string"}},"scimType":{"type":"string","enum":["uniqueness"]},"detail":{"type":"string","enum":["userName must be a unique email"]},"status":{"type":"int","enum":[409]}}}}}}}}}}}
```

## Get User

> Return a single user

```json
{"openapi":"3.1.1","info":{"title":"RiskBase SCIM Version 2.0","version":"0.0.1"},"tags":[{"name":"Users","description":""}],"servers":[{"url":"https://api3.riskbase.uk/sso/{organisationId}/scim/v2"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/Users/{id}":{"get":{"tags":["Users"],"summary":"Get User","description":"Return a single user","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","items":{"type":"string","enum":["urn:ietf:params:scim:schemas:core:2.0:User"]}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"active":{"type":"boolean"},"emails":{"type":"array","items":{"type":"object","properties":{"value":{"type":"email"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"name":{"type":"object","properties":{"formatted":{"type":"string"},"givenName":{"type":"string"},"familyName":{"type":"string"}}},"roles":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"}}}},"meta":{"type":"object","properties":{"resourceType":{"type":"string","enum":["User"]},"created":{"type":"string"},"lastModified":{"type":"string"},"location":{"type":"string"}}}}}}}},"400":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","enum":["urn:ietf:params:scim:api:messages:2.0:Error"]},"scimType":{"type":"string","num":["invalidValue"]},"detail":{"type":"string","enum":["id is required"]},"status":{"type":"int","enum":[400]}}}}}},"404":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","enum":["urn:ietf:params:scim:api:messages:2.0:Error"]},"scimType":{"type":"string","enum":["invalidValue"]},"detail":{"type":"string","enum":["Resource not found"]},"status":{"type":"int","enum":[404]}}}}}}}}}}}
```

## PUT /Users/{id}

> Overwrite User

```json
{"openapi":"3.1.1","info":{"title":"RiskBase SCIM Version 2.0","version":"0.0.1"},"tags":[{"name":"Users","description":""}],"servers":[{"url":"https://api3.riskbase.uk/sso/{organisationId}/scim/v2"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/Users/{id}":{"put":{"tags":["Users"],"summary":"Overwrite User","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["userName","emails","name"],"properties":{"schemas":{"type":"array","enum":["urn:ietf:params:scim:schemas:core:2.0:User"]},"emails":{"description":"The first email with `primary: true` is used; all other emails are discarded.\nThe first email address is used if no emails have `primary: true`; all other emails are discarded\n","type":"array","items":{"type":"object","properties":{"value":{"type":"email"},"primary":{"type":"boolean"}}}},"name":{"type":"object","properties":{"givenName":{"type":"string","required":true},"familyName":{"type":"string","required":true}}},"roles":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"}}}},"active":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"See **Get User**"},"400":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","enum":["urn:ietf:params:scim:api:messages:2.0:Error"]},"scimType":{"type":"string","enum":["invalidValue"]},"detail":{"type":"string","enum":["id is required","userName must be an email"]},"status":{"type":"int","enum":[400]}}}}}},"404":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","items":{"type":"string","enum":["urn:ietf:params:scim:api:messages:2.0:Error"]}},"scimType":{"type":"string","enum":["invalidValue"]},"detail":{"type":"string","enum":["Resource not found"]},"status":{"type":"int","enum":[404]}}}}}},"409":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","items":{"type":"string","enum":["urn:ietf:params:scim:api:messages:2.0:Error"]}},"scimType":{"type":"string","enum":["uniqueness"]},"detail":{"type":"string","enum":["userName must be a unique email"]},"status":{"type":"int","enum":[409]}}}}}}}}}}}
```

## DELETE /Users/{id}

> Delete User

```json
{"openapi":"3.1.1","info":{"title":"RiskBase SCIM Version 2.0","version":"0.0.1"},"tags":[{"name":"Users","description":""}],"servers":[{"url":"https://api3.riskbase.uk/sso/{organisationId}/scim/v2"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/Users/{id}":{"delete":{"tags":["Users"],"summary":"Delete User","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Complete"},"400":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","enum":["urn:ietf:params:scim:api:messages:2.0:Error"]},"scimType":{"type":"string","enum":["invalidValue"]},"detail":{"type":"string","enum":["id is required"]},"status":{"type":"int","enum":[400]}}}}}},"404":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","enum":["urn:ietf:params:scim:api:messages:2.0:Error"]},"scimType":{"type":"string","enum":["invalidValue"]},"detail":{"type":"string","enum":["Resource not found"]},"status":{"type":"int","enum":[404]}}}}}}}}}}}
```

## PATCH /Users/{id}

> Update User

```json
{"openapi":"3.1.1","info":{"title":"RiskBase SCIM Version 2.0","version":"0.0.1"},"tags":[{"name":"Users","description":""}],"servers":[{"url":"https://api3.riskbase.uk/sso/{organisationId}/scim/v2"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/Users/{id}":{"patch":{"tags":["Users"],"summary":"Update User","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["Operations"],"properties":{"schemas":{"type":"array","items":{"type":"string","enum":["urn:ietf:params:scim:schemas:core:2.0:User"]}},"Operations":{"type":"array","items":{"type":"object","properties":{"op":{"type":"string","enum":["add","replace","remove"]},"path":{"type":"string","enum":["name","name.givenName","name.familyName","emails","active","roles"]},"value":{"type":"string | array | object"}}},"required":true}}}}}},"responses":{"200":{"description":"See **Get User**"},"400":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","enum":["urn:ietf:params:scim:api:messages:2.0:Error"]},"scimType":{"type":"string","enum":["invalidValue"]},"detail":{"type":"string","enum":["id is required","userName must be an email"]},"status":{"type":"int","enum":[400]}}}}}},"404":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","enum":["urn:ietf:params:scim:api:messages:2.0:Error"]},"scimType":{"type":"string","enum":["invalidValue"]},"detail":{"type":"string","enum":["Resource not found"]},"status":{"type":"int","enum":[404]}}}}}},"409":{"content":{"application/json":{"schema":{"properties":{"schemas":{"type":"array","items":{"type":"string","enum":["urn:ietf:params:scim:api:messages:2.0:Error"]}},"scimType":{"type":"string","enum":["uniqueness"]},"detail":{"type":"string","enum":["userName must be a unique email"]},"status":{"type":"int","enum":[409]}}}}}}}}}}}
```