SCIM Users

Schema

User

SCIM Attribute	Kojo Attribute	Type	Description
id	id	string	The immutable, unique identifier of a user in Kojo.
active	N/A	boolean	Whether the user can login to your org or not.
admin	admin	boolean	Whether the user has full admin privileges in Kojo or not.
displayName	name	string	The user's display name.
externalId	id	string	(Optional) The user's ID in your system.
phone	phone	string	The user's phone number.
role	UserRole	string	The user's role in your org.
userName	email	string	The user's email address.

UserRole

Value	Description
"BackOffice"	The user will have access to Kojo Office, but is not listed as a Purchasing Agent in various places
"Field"	The user will have access to Kojo Jobsite
"FieldOrdering"	The user will have access to Kojo Jobsite and may send Orders directly to vendors
"Procurement"	The user will have access to Kojo Office
"Warehouse"	The user will have access to the warehouse module in Kojo
"Unassigned"	The user will have no access to Kojo

SCIM Endpoints

GET /Users

Read multiple users, with optional filtering.

Filtering

Note that Kojo does not fully implement filtering for this resource. We only support filtering by userName, and specifically only with the eq operation.

Response

A list of User objects.

Example Request

GET https://api.kojo.tech/scim/v2/Users

Example Response

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 4,
  "Resources": [
    {
      "active": true,
      "admin": false,
      "displayName": "Jack Black",
      "userName": "jack@usekojo.com",
      "externalId": "5bc414ef-f3c3-4d7c-beac-3b747c19115a",
      "id": "clc10266a005apt2ax1h1i76b",
      "meta": {
        "resourceType": "User",
        "created": "2022-12-23T21:03:21.539Z",
        "lastModified": "2022-12-23T21:03:21.539Z",
        "location": "https://api.kojo.tech/scim/v2/Users/clc10266a005apt2ax1h1i76b"
      },
      "phone": "123-456-7890",
      "role": "Field",
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ]
    },
    // ... other results truncated for documentation readability
  ]
}

GET /Users/:id

Read a single user.

Response

A single User object.

Example Request

GET https://api.kojo.tech/scim/v2/Users/clc10266a005apt2ax1h1i76b

Example Response

{
  "active": true,
  "admin": false,
  "displayName": "Jack Black",
  "userName": "jack@usekojo.com",
  "externalId": "5bc414ef-f3c3-4d7c-beac-3b747c19115a",
  "id": "clc10266a005apt2ax1h1i76b",
  "meta": {
    "resourceType": "User",
    "created": "2022-12-23T21:03:21.539Z",
    "lastModified": "2022-12-23T21:03:21.539Z",
    "location": "https://api.kojo.tech/scim/v2/Users/clc10266a005apt2ax1h1i76b"
  },
  "phone": "123-456-7890",
  "role": "Field",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ]
}

POST /Users

Create a new user.

Parameters

Unless otherwise noted, parameters below are required.

Name	Type	Description	Default	Example
admin	boolean	(Optional) If the user is an admin	false	true
displayName	string	The user's display name		"Abraham Lincoln"
externalId	string?	(Optional) The user's ID in your system		"fe44a22d-e4da-42ca-a47b-3f91200763f7"
phone	string?	(Optional) The user's phone number	""	"123-456-7890"
role	UserRole	(Optional) The user's role	"UNASSIGNED"	"Field"
userName	string	The user's unique email address		"abe@usekojo.com"

Response

A 201 Created response with a Location header pointing to the newly created user.

Example Request

POST https://api.kojo.tech/scim/v2/Users
Content-Type: application/scim+json

{
  "active": true,
  "admin": true,
  "displayName": "Abraham Lincoln",
  "userName": "abe@usekojo.com",
  "externalId": "fe44a22d-e4da-42ca-a47b-3f91200763f7",
  "phone": "123-456-7890",
  "role": "Procurement"
}

Example Response

{
  "active": true,
  "admin": true,
  "displayName": "Abraham Lincoln",
  "userName": "abe@usekojo.com",
  "externalId": "fe44a22d-e4da-42ca-a47b-3f91200763f7",
  "id": "clcb21hqp0000kw01jlnsj4w3",
  "meta": {
    "resourceType": "User",
    "created": "2022-12-30T21:56:30.865Z",
    "lastModified": "2022-12-30T21:56:30.865Z",
    "location": "https://api.kojo.tech/scim/v2/Users/clcb21hqp0000kw01jlnsj4w3"
  },
  "phone": "123-456-7890",
  "role": "Procurement",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ]
}

PUT /Users/:id

Update a user.

Parameters

All parameters below are optional.

Name	Type	Description	Example
active	boolean	(Optional) If the user is active	true
admin	boolean	(Optional) If the user is an admin	true
displayName	string	(Optional) The user's display name	"Abraham Lincoln"
externalId	string?	(Optional) The user's ID in your system	"fe44a22d-e4da-42ca-a47b-3f91200763f7"
phone	string?	(Optional) The user's phone number	"123-456-7890"
role	UserRole	(Optional) The user's role	"Field"
userName	string	(Optional) The user's unique email address	"abe@usekojo.com"

Response

A 200 OK response with the updated User object.

Example Request

PUT https://api.kojo.tech/scim/v2/Users/clcb21hqp0000kw01jlnsj4w3
{
  "active": true,
  "admin": false,
  "displayName": "Abraham Lincoln",
  "userName": "abe@usekojo.com",
  "externalId": "fe44a22d-e4da-42ca-a47b-3f91200763f7",
  "phone": "123-456-7890",
  "role": "BackOffice"
}

Example Response

{
  "active": true,
  "admin": false,
  "displayName": "Abraham Lincoln",
  "userName": "abe@usekojo.com",
  "externalId": "fe44a22d-e4da-42ca-a47b-3f91200763f7",
  "id": "clcb21hqp0000kw01jlnsj4w3",
  "meta": {
    "resourceType": "User",
    "created": "2022-12-30T21:56:30.865Z",
    "lastModified": "2022-12-30T22:00:02.707Z",
    "location": "https://api.kojo.tech/scim/v2/Users/clcb21hqp0000kw01jlnsj4w3"
  },
  "phone": "123-456-7890",
  "role": "BackOffice",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ]
}

PATCH /Users/:id

Update a user.

Notes

The PATCH request body is different than other SCIM requests. It follows the urn:ietf:params:scim:api:messages:2.0:PatchOp schema as defined in RFC7644. Below is a table showing the supported operations for each attribute path:

Path	Operations	Notes
active	replace
admin	add, replace	admin defaults to false when creating a user, however we support the add operation as a replace since some SCIM clients use this.
displayName	replace
externalId	add, remove, replace
phone	add, remove, replace
role	add, replace	role defaults to "UNASSIGNED" when creating a user, however we support the add operation as a replace since some SCIM clients use this.
userName	replace

Response

A 200 OK response with the updated User object.

Example Request

PUT https://api.kojo.tech/scim/v2/Users/clcb21hqp0000kw01jlnsj4w3
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "role",
      "value": "BackOffice"
    }
  ]
}

Example Response

{
  "active": true,
  "admin": true,
  "displayName": "Abraham Lincoln",
  "userName": "abe@usekojo.com",
  "externalId": "fe44a22d-e4da-42ca-a47b-3f91200763f7",
  "id": "clcb21hqp0000kw01jlnsj4w3",
  "meta": {
    "resourceType": "User",
    "created": "2022-12-30T21:56:30.865Z",
    "lastModified": "2022-12-30T22:00:02.707Z",
    "location": "https://api.kojo.tech/scim/v2/Users/clcb21hqp0000kw01jlnsj4w3"
  },
  "phone": "123-456-7890",
  "role": "BackOffice",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ]
}

DELETE /Users/:id

Delete a user.

Response

A 204 No Content response on success.

Example Request

DELETE https://api.kojo.tech/scim/v2/Users/clcb21hqp0000kw01jlnsj4w3

Example Response

HTTP/1.1 204 No Content