# Get Current User

> GET /v1/users/current · Access management API

Source: https://developer.kustomer.com/api/access-management/get-current-user

```http
GET https://{orgname}.api.kustomerapp.com/v1/users/current
Authorization: Bearer <API key>
```

## Authorization

Any API key or signed-in user. No specific role is required; any valid credential works.

Retrieves the current user.

## About Users

A user is an account that works in your Kustomer org, such as an agent, an admin or a collaborator, or the machine user behind an API key. Users are the people and integrations doing the support work, as opposed to customers, who receive it.

Users appear throughout Kustomer as the authors of messages and notes, the assignees of conversations, and the members of [teams](https://developer.kustomer.com/api/access-management#teams). Admins invite people from Kustomer's user settings or with `POST /v1/users`, which creates the account and emails an invitation. The user stays pending until they accept it. Creating an [API key](https://developer.kustomer.com/api/access-management#auth-tokens) creates a machine user too, and anything the key changes is attributed to that user. Users aren't deleted: deactivating one keeps their history and lets you restore them later.

#### User types

| `userType` | Who |
| --- | --- |
| `user` | A full user, such as an agent or admin |
| `limited` | A collaborator, with limited access |
| `machine` | The machine user behind an API key |

`GET /v1/users` filters with `userType`, `pending` (`true` for invitations not yet accepted), `deleted` (`true` for deactivated users) or `email`. Use one filter per request; the only combination that works is `deleted` with `userType`, such as `userType=user&deleted=false` for active full users.

#### Roles and role groups

What a user can do comes from `roles` and from [role groups](https://developer.kustomer.com/api/access-management#role-groups). A user can have one role group assigned directly in `roleGroups`, and gets more through their teams. When you invite or update a user, you can't give them more permissions than you have yourself: roles beyond your own are filtered out automatically.

#### Current user and deactivation

`/v1/users/current` is the user behind the token you're calling with: the person for a session or OAuth token, or the machine user for an API key. It works with any valid token, and it's the easy way to find an API key's machine user ID, for example to give it an avatar. `PUT /v1/users/current` updates your own profile, and accepts a new `password` together with `currentPassword`.

To deactivate someone, send `PUT /v1/users/{id}` with `deleted: true`. Send `deleted: null` to restore them.

#### Which endpoint to use

| To | Call |
| --- | --- |
| Find out who the token you're using belongs to | [`GET /v1/users/current`](https://developer.kustomer.com/api/access-management/get-current-user) |
| Update your own profile or password | [`PUT /v1/users/current`](https://developer.kustomer.com/api/access-management/update-current-user) |
| List or search users by type, status or email | [`GET /v1/users`](https://developer.kustomer.com/api/access-management/get-users) |
| Read one user | [`GET /v1/users/{id}`](https://developer.kustomer.com/api/access-management/get-user-by-id) |
| Read several users at once, such as a team's members | [`GET /v1/users/{ids}`](https://developer.kustomer.com/api/access-management/get-multiple-users-by-ids), with comma-separated IDs |
| Invite a new user | [`POST /v1/users`](https://developer.kustomer.com/api/access-management/create-invite-new-user) |
| Change a user's profile, type, roles or role group, or deactivate or restore them | [`PUT /v1/users/{id}`](https://developer.kustomer.com/api/access-management/update-user-by-id) |
| Send a password reset email | [`POST /v1/users/passwordreset`](https://developer.kustomer.com/api/access-management/reset-users-password) |

`POST /v1/users/passwordreset` needs no authentication: send the org `domain` and the user's `email`, and Kustomer emails a link for setting a new password. Reading users needs a user read role; inviting and updating other users needs an admin user role. `GET /v1/users` is paginated with `page` and `pageSize` (up to 500). To list the teams a user is on, use [`GET /v1/users/{id}/teams`](https://developer.kustomer.com/api/access-management/get-a-users-teams).

Related: [Teams](https://developer.kustomer.com/api/access-management#teams), [Role groups](https://developer.kustomer.com/api/access-management#role-groups), [API keys and auth tokens](https://developer.kustomer.com/api/access-management#auth-tokens), [API keys and roles](https://developer.kustomer.com/docs/get-started/api-keys-and-roles)

### Recipes

#### 1. Invite a new agent unless they already have an account

Look a person up by email and invite them with a chosen role group only if they aren't a user yet, the core of provisioning from an HR or identity system.

**Step 1.** [`GET /v1/users`](https://developer.kustomer.com/api/access-management/get-users.md). Search by email. The match is exact and ignores case, and it also finds deactivated users. An empty `data` array means nobody in the org has that address.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/users?email=$EMAIL" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/users --query email=$EMAIL | jq -r '.data[] | [.id, .attributes.name] | @tsv'
```

**Step 2.** [`GET /v1/role-groups`](https://developer.kustomer.com/api/access-management/get-all-role-groups.md). Find the ID of the role group the new agent should get. Match on `name`, because custom role group IDs differ between orgs.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/role-groups?pageSize=100" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/role-groups --all \
  | jq -r 'select(.data.attributes.name == "Agent") | .data.id'
```

**Step 3.** [`POST /v1/users`](https://developer.kustomer.com/api/access-management/create-invite-new-user.md). Create the user with `name`, `email` and `roleGroups`. Kustomer emails them an invitation, and they count as pending until they accept it. Send `roleGroups` explicitly so you know what they can do; roles you don't hold yourself are dropped.

```bash title="cURL"
curl --request POST "https://api.kustomerapp.com/v1/users" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"name\": \"$NAME\", \"email\": \"$EMAIL\", \"userType\": \"user\", \"roleGroups\": [\"$ROLE_GROUP_ID\"]}"
```

```bash title="kusty"
kusty api POST /v1/users --field name="$NAME" --field email=$EMAIL \
  --field userType=user --field "roleGroups:=[\"$ROLE_GROUP_ID\"]"
```

> If the lookup finds someone who has left, restore that account with `PUT /v1/users/{id}` and `"deleted": null` rather than inviting them again. `GET /v1/users?deleted=true` lists deactivated users. Use `userType: limited` to invite a collaborator instead; Kustomer then assigns the collaborator role group itself.

#### 2. Offboard a user who has left

Deactivate someone's account and take them off their teams, for example when an HR system reports a leaver.

**Step 1.** [`GET /v1/users`](https://developer.kustomer.com/api/access-management/get-users.md). Find the user's ID from their email address.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/users?email=$EMAIL" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
USER_ID=$(kusty api GET /v1/users --query email=$EMAIL | jq -r '.data[0].id')
```

**Step 2.** [`PUT /v1/users/{id}`](https://developer.kustomer.com/api/access-management/update-user-by-id.md). Set `deleted` to `true` to deactivate the user. The record stays, so their conversations, notes and audit history still point to them, and the update changes only the fields you send.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/users/$USER_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"deleted": true}'
```

```bash title="kusty"
kusty api PUT /v1/users/$USER_ID --field deleted:=true
```

**Step 3.** [`GET /v1/users/{id}/teams`](https://developer.kustomer.com/api/access-management/get-a-users-teams.md). Deactivating a user doesn't take them off their teams. List the teams they're still on, skipping deleted teams.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/users/$USER_ID/teams?deleted=false" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/users/$USER_ID/teams --query deleted=false | jq -r '.data[].id' > teams.txt
```

**Step 4.** [`DELETE /v1/teams/{id}/members`](https://developer.kustomer.com/api/access-management/remove-team-member.md). Remove the user from each team. Only the IDs you send are removed; the other members stay.

```bash title="cURL"
curl --request DELETE "https://api.kustomerapp.com/v1/teams/$TEAM_ID/members" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"members\": [\"$USER_ID\"]}"
```

```bash title="kusty"
while read -r TEAM_ID; do
  kusty api DELETE /v1/teams/$TEAM_ID/members --field "members:=[\"$USER_ID\"]" --confirm --yes
done < teams.txt
```

> To bring someone back, send `"deleted": null` to `PUT /v1/users/{id}` and add them to their teams again. If a team they were still on is already at its member limit when they're restored, Kustomer takes them off that team.

#### 3. Export a roster of active agents

Produce a CSV of everyone who can sign in as a full user, with their role groups, for an access review.

**Step 1.** [`GET /v1/users`](https://developer.kustomer.com/api/access-management/get-users.md). Combine `userType=user` with `deleted=false` to get active full users, leaving out API key users and collaborators. This is the one pair of filters that works together. Pending invitations are included, and `password.forceNew` is still `true` for them.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/users?userType=user&deleted=false&pageSize=500" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/users --query userType=user --query deleted=false --query pageSize=500 --all \
  --output jsonl > users.jsonl
```

**Step 2.** Write one row per user. `roleGroups` holds the ID of the role group assigned directly; teams can add more, so read [teams](https://developer.kustomer.com/api/access-management#teams) as well if your review needs everything a person can do.

```bash title="kusty"
jq -r '.data | [.id, .attributes.name, .attributes.email, (.attributes.roleGroups | join(";"))] | @csv' \
  users.jsonl > roster.csv
```

#### 4. Turn a list of user IDs into names

Resolve the user IDs found on conversations, notes or audit log entries in one request instead of one per user.

**Step 1.** Collect the distinct IDs you need, such as `relationships.createdBy.data.id` from notes or `userId` from a page of [audit log entries](https://developer.kustomer.com/api/core-resources/query-events-associated-with-your-organization) saved as `audit-logs.json`, and join them with commas.

```bash title="kusty"
IDS=$(jq -r '.data[].attributes.userId // empty' audit-logs.json | sort -u | paste -sd, -)
```

**Step 2.** [`GET /v1/users/{ids}`](https://developer.kustomer.com/api/access-management/get-multiple-users-by-ids.md). Request them together. IDs that don't match a user in your org are left out of the response, and if you pass a single ID, `data` is one object rather than an array, so handle both shapes.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/users/$IDS" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/users/$IDS \
  | jq -r '.data | if type == "array" then .[] else . end | [.id, .attributes.displayName] | @tsv'
```

> `displayName` falls back to `name` when the user hasn't set one, so it's the better field to show. Cache the result; names change rarely.

### Example object

A real record from [`POST /v1/users`](https://developer.kustomer.com/api/access-management/create-invite-new-user.md):

```json
{
  "type": "user",
  "id": "582922c07c7f551a00b5b73a",
  "attributes": {
    "displayName": null,
    "avatarUrl": "https://media.kustomerapp.com/media/some/path.png",
    "name": "John Smith",
    "userType": "user",
    "email": "johnsmith@example.com",
    "mobile": null,
    "emailSignature": null,
    "password": {
      "allowNew": true,
      "forceNew": true,
      "updatedAt": "2016-11-14T02:34:40.999Z"
    },
    "roles": [
      "org.admin",
      "org.user"
    ],
    "roleGroups": [
      "5afee08eb06db6d51b8cf61e"
    ],
    "updatedAt": "2016-11-14T02:34:40.988Z",
    "createdAt": "2016-11-14T02:34:40.988Z"
  },
  "relationships": {
    "org": {
      "links": {
        "self": "/v1/orgs/57bb5d2e32e83a130052e94e"
      },
      "data": {
        "type": "org",
        "id": "57bb5d2e32e83a130052e94e"
      }
    }
  },
  "links": {
    "self": "/v1/users/582922c07c7f551a00b5b73a"
  }
}
```

Fields:

- `attributes.displayName` (string): Optional name to show instead of `name`. When none is set, the API returns `name` here.
- `attributes.avatarUrl` (string): URL of the user's profile picture. Give an API key's machine user one so the integration's activity is easy to spot on timelines.
- `attributes.name` (string): The user's full name, up to 256 characters. Required when inviting.
- `attributes.userType` (string): `user` for a full user, `limited` for a collaborator, or `machine` for the user behind an API key. For `limited` users Kustomer ignores `roles` and assigns the collaborator role group.
- `attributes.email` (string): The sign-in address, stored in lowercase. `GET /v1/users?email=` matches it exactly, ignoring case.
- `attributes.emailSignature` (string): The user's email signature, up to 1,024 characters.
- `attributes.password` (object): The state of the user's password. The password itself is never returned.
- `attributes.password.allowNew` (boolean): `true` when the user can set a new password without giving the current one, as after an invitation or a reset.
- `attributes.password.forceNew` (boolean): `true` until the user sets a password of their own, for example after an invitation or a reset.
- `attributes.password.updatedAt` (string): When the password was last set or reset.
- `attributes.roles` (array): Roles granted to the user directly, on top of those from role groups. Roles you don't hold yourself are dropped when you invite or update a user.
- `attributes.roleGroups` (array): The role group (permission set) assigned directly, as a list of at most one ID. Teams can add more. Sending `roleGroups` on `PUT` replaces it.

### Relationships

- Points to **Role groups** via `relationships.roleGroups` (list): The role group assigned directly to a user, in the user's `roleGroups`. Role groups don't list their members, so read users and teams to find who has one.
- Referenced by **AI automations** via `relationships.user`: The machine user an AI automation acts as in Kustomer, the same ID as the automation's `machineUserId`.
- Referenced by **API keys and auth tokens** via `relationships.user`: The user an auth token acts as, either the person who signed in or the machine user created for an API key. Anything the token changes is attributed to that user.
- Referenced by **Audit logs** via `relationships.user`: The user whose action an audit log entry records. `filter[userId]` returns the entries by or about one user.
- Referenced by **Comments** via `relationships.userMentions` (list): The users mentioned in a comment, sent as `userMentions` when you create or edit it. An entry can be a team instead, typed `team`.
- Referenced by **Conversation time** via `relationships.handleBy`: The agent whose action captured this conversation time record. Only records from the v2 timer have it.
- Referenced by **Knowledge base articles** via `relationships.accessUsers` (list): Users allowed to see an internal knowledge base article, set on a draft with `accessUsers` and applied when it's published.
- Referenced by **Notifications** via `relationships.user`: The user a notification is for. Each user only sees their own notifications and preferences, so read them with that user's credentials rather than an integration's API key.
- Referenced by **Saved searches** via `relationships.userVisibilities` (list): The users a saved search is shown to, from the `id` of each `userVisibilities` entry. These entries apply on top of the search's `defaultVisibility`.
- Referenced by **Settings** via `relationships.user`: For user settings, the user whose preference a setting is. Org settings belong to the whole org and have no user.
- Referenced by **Shortcuts** via `relationships.accessUsers` (list): The users a shortcut is limited to, from its `accessUsers` list of up to 10 user IDs, in addition to any teams in `accessTeams`.
- Referenced by **Teams** via `relationships.members` (list): The users on a team, from the team's `members` list of user IDs. A user can be on any number of teams; `GET /v1/users/{id}/teams` lists one user's teams.
- Referenced by **Work items** via `relationships.routedTo`: The agent this work item was last offered to.
- Referenced by **Work items** via `relationships.assignedTo`: The agent this work item is assigned to.
- Referenced by **Work items** via `relationships.acceptedBy`: The agent who accepted this work item.
- Referenced by **Work sessions** via `relationships.user`

### Permissions

Fewest roles for a read-only integration: `org.permission.user.read`. For every endpoint: `org.permission.user.read`, `org.permission.user.create`, `org.permission.user.update`.

### Events

Webhook events:

- `kustomer.user.create`: A user (agent or machine user) is added
- `kustomer.user.update`: A user's profile, roles or teams change

Workflow actions:

- `kustomer.user.find-by-id` (User: Find By ID): required inputs `id`
- `kustomer.user.find-by-email` (User: Find By Email): required inputs `email`

## Responses

### 200

OK

- `data` (object, required)
  - `type` (string, required)
  - `id` (string, required)
  - `attributes` (object, required)
    - `displayName` (string, required, nullable)
    - `avatarUrl` (string, required)
    - `name` (string, required)
    - `userType` (string, required)
    - `email` (string, required)
    - `emailVerifiedAt` (string, required)
    - `mobile` (string, required, nullable)
    - `password` (object, required)
    - `roles` (array<string>, required)
    - `updatedAt` (string, required)
    - `createdAt` (string, required)
  - `relationships` (object, required)
    - `org` (object, required)
  - `links` (object, required)
    - `self` (string, required)

```json
{
  "data": {
    "type": "user",
    "id": "57bb5d2e32e83a130052e94f",
    "attributes": {
      "displayName": null,
      "avatarUrl": "https://media.kustomerapp.com/media/some/path.png",
      "name": "Alex Mercer",
      "userType": "user",
      "email": "alex.mercer@example.com",
      "emailVerifiedAt": "2016-10-02T03:56:28.248Z",
      "mobile": null,
      "password": {
        "allowNew": false,
        "forceNew": false,
        "updatedAt": "2016-10-02T03:56:38.765Z"
      },
      "roles": [
        "org",
        "system"
      ],
      "updatedAt": "2016-10-02T03:56:38.762Z",
      "createdAt": "2016-08-22T20:14:38.450Z"
    },
    "relationships": {
      "org": {
        "links": {
          "self": "/v1/orgs/57bb5d2e32e83a130052e94e"
        },
        "data": {
          "type": "org",
          "id": "57bb5d2e32e83a130052e94e"
        }
      }
    },
    "links": {
      "self": "/v1/users/current"
    }
  }
}
```

### 401

Unauthorized - Authentication required or invalid credentials

### 403

Forbidden - Insufficient permissions

### 404

Not Found - Resource does not exist

## Example request

```bash
curl --request GET \
  --url 'https://api.kustomerapp.com/v1/users/current' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```