Users

Users #

Users belong to an organization. Users may belong to Roles, and can have Permissions to various Resources.

Create a User #

HTTP POST /orgs/{orgId}/users

# For example:
HTTP POST /orgs/example.com/users

Payload:

{
	"id": "user3",
	"identityProviderUserId": "jeswinpk@agilehead.com",
	"identityProvider": "Google",
	"data": "data for aser3"
}

Response:

{
	"data": {
		"roleIds": [],
		"properties": {},
		"id": "user3",
		"data": "data for aser3",
		"identityProvider": "Google",
		"identityProviderUserId": "jeswinpk@agilehead.com",
		"createdAt": "2023-07-06T13:01:26.6594794Z",
		"orgId": "example.com"
	}
}

Get Users #

HTTP GET /orgs/{orgId}/users/

For example:
HTTP GET /orgs/example.com/users/

Response:

{
	"data": [
		{
			"roleIds": [],
			"properties": {},
			"id": "user3",
			"data": "data for aser3",
			"identityProvider": "Google",
			"identityProviderUserId": "jeswinpk@agilehead.com",
			"createdAt": "2023-07-06T13:01:26.659479Z",
			"orgId": "example.com"
		}
	]
}

To get a single user (as a list with one item), specify the user’s id.

HTTP GET /orgs/{orgId}/users/{userId}

# For example
HTTP GET /orgs/example.com/users/user3

You can specify multiple user ids.

HTTP GET /orgs/{orgId}/users/{userId}

# For example
HTTP GET /orgs/example.com/users/user3,user5

Get Users by Identity Provider #

HTTP GET /orgs/{orgId}/users/?identityProvider={identityProvider}&identityProviderUserId={identityProviderUserId}

For example:
HTTP GET /orgs/example.com/users/?identityProvider=Google&identityProviderUserId=jeswinpk@agilehead.com

Response:

{
	"data": [
		{
			"roleIds": [],
			"properties": {},
			"id": "user3",
			"data": "data for aser3",
			"identityProvider": "Google",
			"identityProviderUserId": "jeswinpk@agilehead.com",
			"createdAt": "2023-07-06T13:01:26.659479Z",
			"orgId": "example.com"
		}
	]
}

By using a wildcard in place of the orgId, you can even search by identityProvider across orgs if your application allows users to be in multiple orgs.

For example, to find users across orgs tied to the identity Google/jeswinpk@agilehead.com, you could use the following query:

HTTP GET /orgs/~/users/?identityProvider=Google&identityProviderUserId=jeswinpk@agilehead.com

Update a user #

HTTP PUT /orgs/{orgId}/users/{userId}

# For example:
HTTP PUT /orgs/example.com/users/user3

Payload:

{
	"identityProviderUserId": "jeswinpk@agilehead.com",
	"identityProvider": "Google",
	"data": "new data for user3"
}

Response:

{
	"data": {
		"roleIds": [],
		"properties": {},
		"id": "user3",
		"data": "new data for user3",
		"identityProvider": "Google",
		"identityProviderUserId": "jeswinpk@agilehead.com",
		"createdAt": "2023-07-06T13:01:26.659479Z",
		"orgId": "example.com"
	}
}

Delete a user #

Deleting a user will also delete associated user permissions.

HTTP DELETE /orgs/{orgId}/users/{userId}

# For example:
HTTP DELETE /orgs/example.com/users/user3

Assiging Roles #

HTTP POST /orgs/{orgId}/users/{userId}/roles

# For example:
HTTP DELETE /orgs/example.com/users/user3/roles

Payload:

{
	"roleId": "admins"
}

Response:

{
	"data": {
		"userId": "user3",
		"roleId": "admins",
		"createdAt": "2023-07-01T11:57:54.0264874Z",
		"orgId": "agilehead.com"
	}
}

Unassigning Roles #

HTTP DELETE /orgs/{orgId}/users/{userId}/roles/{roleId}

# For example:
HTTP DELETE /orgs/example.com/users/user3/roles/admins

Finds users in a Role #

See a list of users who have a specific Role.

HTTP GET /orgs/{orgId}/roles/{roleId}/users

# For example, fetch roles with active = yes
HTTP GET /orgs/example.com/roles/admins/users

Add a Custom Property #

You can add custom string properties to an user entity.

HTTP PUT: /orgs/{orgId}/users/{userId}/properties/{propertyName}

For example:
HTTP PUT: /orgs/example.com/users/user3/properties/firstName

Payload:

{
	"value": "Jeswin"
}

Response:

{
	"data": {
		"name": "firstName",
		"value": "Jeswin",
		"hidden": false,
		"createdAt": "2023-07-06T13:07:41.8782012Z"
	}
}

When properties are added to an user, they are returned when the user is fetched.

For example, GET /orgs/example.com/users/user3 will retrieve the following response. Note the added properties object.

{
	"data": [
		{
			"roleIds": [],
			"properties": {
				"firstName": "Jeswin"
			},
			"id": "user3",
			"data": "new data for user3",
			"identityProvider": "Google",
			"identityProviderUserId": "jeswinpk@agilehead.com",
			"createdAt": "2023-07-06T13:01:26.659479Z",
			"orgId": "example.com"
		}
	]
}

Get the value of a property #

Properties are usually read as a part of the fetching entity; user in this case. But if you need to get a list of properties without fetching the entity you can use the following API.

HTTP GET /orgs/{orgId}/users/{userId}/properties/{propertyName}

# For example:
HTTP GET /orgs/example.com/properties/users/users/user3/firstName

Response:

{
	"data": [
		{
			"userId": "user3",
			"orgId": "example.com",
			"name": "firstName",
			"value": "Jeswin",
			"hidden": false,
			"createdAt": "2023-07-06T13:07:41.878201Z"
		}
	]
}

Delete a Custom Property #

HTTP DELETE: /orgs/{orgId}/users/{userId}/properties/{propertyName}

# For example:
HTTP DELETE: /orgs/example.com/users/user3/properties/firstName

Creating Hidden Properties #

When a property is hidden, it will not be included when the user is fetched. To create a hidden property, add the hidden flag when creating the property.

To create a Hidden Property:

HTTP PUT: /orgs/{orgId}/users/{userId}/properties/{propertyName}

# For example:
HTTP PUT: /orgs/example.com/users/user3/properties/active

Payload should include the hidden attribute:

{
  "active": "yes",
  "hidden": true
}

To include a hidden property when querying users, it should be explicitly mentioned. Note that properties which aren’t hidden are always included.

HTTP GET /orgs/{orgId}/users?properties={propertyName}

For example:
HTTP GET /orgs/example.com/users?properties=active

Response:

{
	"data": [
		{
			"roleIds": [],
			"properties": {
				"active": "yes",
				"firstName": "Jeswin"
			},
			"id": "user3",
			"data": "new data for user3",
			"identityProvider": "Google",
			"identityProviderUserId": "jeswinpk@agilehead.com",
			"createdAt": "2023-07-06T13:01:26.659479Z",
			"orgId": "example.com"
		}
	]
}

Filtering by Property #

users may be filtered by the custom property.

HTTP GET /orgs/{orgId}/users?properties.{propertyName}={propertyValue}

# For example, fetch users with active = yes
HTTP GET /orgs/example.com/users?properties.active=yes

Response:

{
	"data": [
		{
			"roleIds": [],
			"properties": {
				"firstName": "Jeswin"
			},
			"id": "user3",
			"data": "new data for user3",
			"identityProvider": "Google",
			"identityProviderUserId": "jeswinpk@agilehead.com",
			"createdAt": "2023-07-06T13:01:26.659479Z",
			"orgId": "example.com"
		}
	]
}