# User API

> Reference for Holistics' legacy User API endpoints, covering how to invite, delete, restore, and manage users and their API access tokens programmatically.

:::caution Warning
This is a **legacy API**. It is still functional but is **not in active development/ maintenance** anymore. 
:::

These API endpoints allows the admin to manage their users programmatically. 

## How to use these API endpoints

### Obtain API Key 

Before using the API, please obtain the API key by following the [Getting Started guide](/api/v2/getting-started).

### Send API requests to Holistics

To use these APIs, simply append Holistics' host URL `secure.holistics.io` with your chosen endpoint.

 For example, to call the API [Get all users in a tenant with full information](#get-all-users-in-a-tenant-with-full-information), you will have to use **GET** request with this URL: `secure.holistics.io/user.json`.

## Get all users in a tenant with full information

**Sample request:**

```
GET /users.json
```

**Sample response:**

```
[
  {
    "id": 1,
    "name": "Analyst",
    "email": "analyst@holistics.io",
    "role": "analyst",
    "initials": "An",
    "is_deleted": false,
    "is_activated": true,
    "has_authentication_token": true,
    "groups": [
      {
        "id": 33,
        "name": "Capital",
        "created_at": "2015-06-29T03:22:14.842Z",
        "updated_at": "2015-06-29T03:22:14.842Z",
        "tenant_id": 5
      }
    ],
    "allow_authentication_token": true,
    "current_sign_in_at": "2018-10-23T03:35:47.353Z",
    "last_sign_in_at": "2018-10-22T03:21:52.393Z"
  },
  {
    "id": 2,
    "name": "Business User",
    "email": "business@holistics.io",
    "role": "business",
    "initials": "Bu",
    "is_deleted": false,
    "is_activated": true,
    "has_authentication_token": false,
    "groups": [],
    "allow_authentication_token": false,
    "current_sign_in_at": "2018-10-21T03:35:47.353Z",
    "last_sign_in_at": "2018-10-20T03:21:52.393Z"
  },
]
```

:::note
- **current_sign_in_at:** latest sign-in timestamp.
- **last_sign_in_at:** previous sign-in timestamp (before the current_sign_in_at time).
- **allow_authentication_token** is used to determine whether a user **is allowed** for API access (only Admin can update this field for a specific user).
- **has_authentication_token** is used for determining whether a user **has already generated** an API access key (this flag will be turned to false if the Revoke Authentication Token call is requested).
- A **Tenant** is the organization that is using Holistics (e.g. Grab). 
:::

## Invite a new user to Holistics

**Sample request:**

```
POST /users/invite.json
```

**Parameters:**
- **name:** user's full name
- **email:** user's email address
- **role:** user role. At Holistics, there are 4 roles: admin, analyst, explorer, viewer.To learn more about the role system, visit [User Roles](/docs/admin/user-roles).
- **message:** The invitation message that will be sent to the invitee.

**Sample request body:**

```
{
  "name": "Test",
  "email": "tester@tenant.com",
  "role": "user",
  "message": "Hey, let's join MyCompany workspace on Holistics"
}
```

**Sample success response:**

```
{
  "status": "ok"
}
```

**Sample error response when a user already exists in Holistics's database:** 

```
{
  "errors": [
    "Email already existed"
  ]
}
```

You will need to use the [Resend Invitation API](#resend-invitation-to-user) instead. 

## Resend invitation to user

**Sample request:**

```
POST /users/user_id/resend_invite.json
```

**Sample success response:**
```json
{
  "status": "ok"
}
```

## Soft-delete a user

**Sample request:**

```
DELETE /users/user_id.json
```

**Sample success response:**

```json
{
  "status": "ok"
}
```

## Restore a deleted user

**Sample request:**

```
POST /users/restore.json
```

**Sample request body:**

```json
{
  "id": 560
}
```

**Sample error response when attempt to restore a non-deleted user:**

```json
{
  "errors": [
    "User is not deleted"
  ]
}
```

## Allow/ Revoke a user's API access

**Sample request:**

```
PATCH /users/user_id.json
```

**Sample body request:**

```json
{
  "allow_authentication_token": true
}
```

**Sample success response:**

```json
{
  "status": "ok"
}
```

## Revoke Authentication Token from a user

This API is used to revoke generated Authentication Tokens. Consider using this API if: 
- You are worried that the current token may have been leaked. 
- You want to enforce a token refresh for security reasons. 

After their token has been revoked, the user would need to re-generate a new token by following the [Getting Started guide](/api/v2/getting-started).

**Sample request:**

```
POST /users/user_id/revoke_authentication_token.json
```

**Sample success response:**

```json
{
  "status": "ok"
}
```
## Check whether email address is already used for a user in Holistics

**Sample request:**

```
GET /users/check_holistics_user.json/?email={email_address}
```

**Sample success response:**

```json
{
  "is_already_user": true
}
```

## Change user role in Holistics

**Required params:**

- **user_id**
- **user:** an object that contains the needed information for changing user role
    - **role (string):** can be `admin`, `analyst` or `user`
    - **remove_groups (boolean):** false by default. If the params are set to true, then the user's groups will also be removed after the role is changed.

**Sample request:**

```
POST /users/change_user_role.json
```

**Sample body request:**

```json
{
	id: 1,
	user: {
		role: "analyst",
		remove_groups: true
	}
}
```

## Find user by email address

**Sample request:**

```
GET /users/get_user.json/?email={email_address}
```

**Sample success response:**

```json
{
    "id": 1,
    "name": "Business User",
    "email": "business@holistics.io",
    "role": "business",
    "title": null
}
```