Add or remove users

By adding users you can customize access for everyone in your space. Depending on your use case, you can either add regular Kisi users or managed users.

Regular versus managed users

1. Regular users are required to register for a Kisi account. They receive emails from Kisi when they get access shared or credentials assigned.
2. Managed users (also known as white label users) are never required to sign up for a Kisi account. They don't receive emails from Kisi. Logins need to be created on their behalf by an organization owner or by an organization administrator.

info

White label users are now called managed users in Kisi. For white label integrations, make sure you always use managed users. A white label integration refers to an API integration that is embedded within your own corporate identity, not Kisi's.

Add users

Regular users

To add a new user, send a POST request to the Create user endpoint, following the example below.

Example

curl --request POST \
  --url https://api.kisi.io/users \
  --header 'Accept: application/json' \
  --header 'Authorization: KISI-LOGIN <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "user": {
    "send_emails": true,
    "confirm": true,
    "email": "user@example.com"
  }
}'

Response

For regular users, if your request was successful, you'll receive a 200 OK response containing the created user object:

{
  "id": 0,
  "email": "user@example.com",
  "name": "string",
  "confirmed": false
}

Managed users

To add a new managed user, send a POST request to the Create user endpoint, following the example below.

Example

curl --request POST \
  --url https://api.kisi.io/users \
  --header 'Accept: application/json' \
  --header 'Authorization: KISI-LOGIN <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "user": {
    "send_emails": false,
    "confirm": true,
    "email": "user@example.com"
  }
}'

• by setting the confirm parameter to true, you ensure the user will be automatically confirmed upon creation
• by setting the send_emails parameter to false, you ensure the user will not receive notifications from Kisi

info

When creating managed users, make sure you include "send_emails": false. Omitting this parameter will result in the user receiving emails from Kisi.

Response

For managed users, if your request was successful, you'll receive a 200 OK response containing the created user object:

{
  "id": 0,
  "email": "user@example.com",
  "name": "string",
  "confirmed": false
}

Log in on behalf of managed users

Since managed users can't log in to Kisi themselves, an organization owner or an admin has to log in on their behalf.

Send a POST request to the Create login endpoint, following the example below.

Example

curl --request POST \
  --url https://api.kisi.io/logins \
  --header 'Authorization: KISI-LOGIN <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "login": {
    "type": "device",
    "device_brand": "string",
    "device_model": "string",
    "os_name": "string",
    "email": "user-1@example.com"
  },
  "user": {
    "domain": "string",
    "email": "user-2@example.com",
    "password": "string",
    "otp_attempt": "string"
  }
}'

The login object contains information about the login being created.

• type - when logging in managed users, only device logins can be created, i.e. logins connected to a device such as your mobile or laptop
• device_brand - the brand of the device this login will be associated to
• device_model- the model of the device this login will be associated to
• os_name - the name of the OS of the device this login is created from
• email - the email of the user this login is created for

The user object contains authentication information about the user making the request to create a login.

• domain - the user's organization domain
• email - the email of the user creating the login
• password - the password of the user creating the login
• otp_attempt - a one time password to satisfy two-factor authentication. Only required if the user has this option enabled.

Response

If your request was successful, you'll receive a 200 OK response with the login object, the user, and the authentication token associated with this login.

{
  "id": 0,
  "user_id": 0,
  "user": {
    "id": 0,
    "email": "user-1@example.com",
  "secret": "0"
}

• secret - the authentication token used for this login

The login can be used subsequently to make requests to the Kisi API on behalf of the user.

Remove users

If a user leaves your organization, you will want to delete their profile. To achieve this, you will have to first identify the user id.

Send a GET request to the Fetch users endpoint, while using the query parameter to filter by email. See the example below.

curl --request GET \
  --url 'https://api.kisi.io/users?query=user@example.com' \
  --header 'Authorization: KISI-LOGIN <API_KEY>' \
  --header 'Content-Type: application/json' \

Response

If your request was successful, you'll receive a 200 OK response containing the user object and, within it, the related user id.

{
  "id": 0,
  "email": "user@example.com"
  "name": "string"
}

Copy the id value from within the user object, since you'll need this in the next step.

Now that you have the user_id, send a DELETE request to the Delete user endpoint, following the example below.

Example

curl --request DELETE \
  --url https://api.kisi.io/users/<id> \
  --header 'Accept: application/json' \
  --header 'Authorization: KISI-LOGIN <API_KEY>'

Response

If your request was successful, you'll receive a 204 No content response.