Documentation (2024.2 Enterprise)

# User

A user is a human being with a Helix TeamHub account. A user can log into Helix TeamHub.

- Attributes
- Searchable attributes
- Child objects
- Operations
  - `GET /users`
  - `GET /users/:id`
  - `GET /users/:id/projects`
  - `POST /users`
  - `PUT /users/:id`
  - `DELETE /users/:id`
  - `GET /users/count`

## Attributes

### id

A URL-friendly identifier (the username). Must start with a word character ([a-zA-Z0-9_]).

- Type: `string`
- Unique: `true`
- Required: `true`
- Minimum length: `1`
- Maximum length: `100`
- Allowed characters: `a-z`, `A-Z`, `0-9`, `-`, `_`, `+`, `.`

### designer (Helix DAM only)

Whether the user is a designer and has access to the Helix DAM web UI.

- Type: `boolean`
- Default: `false`

### email

The user's email address.

- Type: `string`
- Unique: `true`
- Required: `true`

### registration_email

You may use the optional `registration_email` address when creating a new user whose `email` address does not yet exist. The registration email will be sent to this address instead of the user's `email` address.

- Type: `string`

### first_name

The user's first name.

- Type: `string`
- Maximum length: `32`

### last_name

The user's last name.

- Type: `string`
- Maximum length: `32`

### display_name

The display_name is automatically generated from user's attributes. Primarily both first_name and last_name are used. In case either one of them is absent, will the present one be used by itself. As a last resort, the email attribute is used.

- Type: `string`

### password

A new password for the user (can be in plaintext or already hashed). You can omit the password attribute from the request if you do not want to set or update it. Users created without password attribute will get a link to set the initial password within the registration email, unless LDAP only authentication method is used in the Helix TeamHub instance. Validations depend on instance specific configurations.

- Type: `string`
- Default minimum length: `8`
- Default maximum length: `100`

### pre_hash

The hash algorithm if the value of the password attribute has already been hashed externally. This is mainly used for users that are synchronized from external systems. For example, passwords stored in LDAP directories are already digested.

- Type: `string`
- Default: `null`
- Allowed algorithms: `ldap_sha1`, `ldap_md5`, `null`

### password_changed_at

Timestamp of the last password change when password expiration is enabled.

- Type: `timestamp`

### password_expires_at

Timestamp when the password will expire when password expiration is enabled.

- Type: `timestamp`

### password_expired

Current password expiration status when password expiration is enabled.

- Type: `boolean`

### password_never_expires

Whether or not the password will never expire for an account. Allows disabling password expiration for an account when password expiration is enabled. Only company admins can update the value.

- Type: `boolean`
- Default: `false`

### synchronized_fields

An array of attributes in User API, which are actively being updated from external source, such as LDAP or AD.

- Type: `string`
- Default: `[]`

### company_admin

Whether or not the user has admin privileges for the company.

- Type: `boolean`
- Default: `false`

### instance_admin

Whether or not the user has admin privileges for the instance.

- Type: `boolean`
- Default: `false`

### description

A free form profile description of the user.

- Type: `string`
- Default: `""`
- Maximum length: `512`

### phone

The user's phone number.

- Type: `string`
- Default: `""`
- Maximum length: `32`
- Allowed characters: `0-9`, `+`, `-`

### title

The user's title in the company, for example "Software Engineer".

- Type: `string`
- Default: `""`
- Maximum length: `60`

### locale

The user's locale.

- Type: `string`
- Default: `en`
- Allowed values: `en`, `zh`

### source

The identifier of the external source where the user is synchronized from.

- Type: `string`
- Default: `""`
- Maximum length: `500`

### last_login_at

Timestamp of the last time the user logged in to Helix TeamHub. If the user has never logged in, the response is null.

- Type: `timestamp`

### login_count

The number of times the user has logged in to Helix TeamHub.

- Type: integer

### helix_auth_method

Helix authentication method used by the user. Valid responses when the user has Helix authentication, "perforce" or "ldap". If the user is not using Helix authentication, an empty string is returned.

- Type: string
- Default: "perforce" if Helix authentication is configured

### avatar

The avatar of the user, as a child object.

- Type: `object`
- Default: `{}`

The avatar objects contains URLs to the avatar image in several sizes:

    "avatar": {
      "large": "system/uploads/4f85e344-6156-418f-baf0-d4b65c9df148-100x100.jpg",
      "medium": "system/uploads/4f85e344-6156-418f-baf0-d4b65c9df148-60x60.jpg",
      "small": "system/uploads/4f85e344-6156-418f-baf0-d4b65c9df148-30x30.jpg"
    }

## Searchable attributes

Users can be searched by their `id`, `email`, and `display_name` attributes. See the search documentation for instructions how to do this.

## Child objects

The following child objects can be attached to the users returned, to eliminate the need for requesting them separately:

Object | Attribute
--- | ---
Project | `projects`
Repository | `repositories`

For example, to get all of the user's projects in full, attach `include=projects` to your GET request.

See the child object API documentation for a description of the possible operations.

## Operations

### GET /users

Returns all the users in the company, with optional limit and offset parameters, as a metadata-results object.

#### Example request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/users

#### Example response

    {
      "metadata": {
        "more_results": false,
        "next_offset": 2,
        "count": 2
      },
      "results": [
        {
          "api_status": 200,
          "api_timestamp": "2019-10-24T14:03:48Z",
          "id": "norris",
          "created_at": "2019-10-24T14:03:48Z",
          "updated_at": "2019-10-24T14:03:48Z",
          "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
          "type": "user",
          "email": "chuck.norris@company.com",
          "short_name": "cnorris",
          "first_name": "Chuck",
          "last_name": "Norris",
          "display_name": "Chuck Norris",
          "company_admin": true,
          "instance_admin": true,
          "description": "Walker Texas Ranger",
          "phone": "",
          "title": "Executive Executor",
          "avatar": {
            "api_status": 200,
            "api_timestamp": "2019-10-24T14:03:48Z",
            "id": "YYYYYY-YYYY-YYYY-YYYY-YYYYYYYY",
            "created_at": "2019-10-24T14:03:48Z",
            "updated_at": "2019-10-24T14:03:48Z",
            "large": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-100x100.jpg",
            "medium": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-60x60.jpg",
            "small": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-30x30.jpg"
          },
          "synchronized_fields": [
            "short_name"
          ],
          "locale": "en",
          "source": ""
          "last_login_at": "2019-10-24T14:03:53Z",
          "login_count": 1,
          "password_given": true,
          "password_changed_at": null,
          "password_expires_at": null,
          "password_expired": false,
          "password_never_expires": false,
          "helix_auth_method": ""
        },
        {
          "api_status": 200,
          "api_timestamp": "2019-10-24T14:03:48Z",
          "id": "ckent",
          "created_at": "2019-10-24T14:03:48Z",
          "updated_at": "2019-10-24T14:03:48Z",
          "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
          "type": "user",
          "email": "clark.kent@company.com",
          "short_name": "ckent",
          "first_name": "Clark",
          "last_name": "Kent",
          "display_name": "Clark Kent",
          "company_admin": false,
          "instance_admin": false,
          "description": "",
          "phone": "+358 1234 567",
          "title": "Software engineer",
          "avatar":{
            "api_status": 200,
            "api_timestamp": "2019-10-24T14:03:48Z",
            "id": "YYYYYY-YYYY-YYYY-YYYY-YYYYYYYY",
            "created_at": "2019-10-24T14:03:48Z",
            "updated_at": "2019-10-24T14:03:48Z",
            "large": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-100x100.jpg",
            "medium": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-60x60.jpg",
            "small": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-30x30.jpg"
          },
          "synchronized_fields": [
            "short_name"
          ],
          "locale": "en",
          "source": "external"
          "last_login_at": "2019-10-24T14:03:54Z",
          "login_count": 2,
          "password_given": true,
          "password_changed_at": null,
          "password_expires_at": null,
          "password_expired": false,
          "password_never_expires": false,
          "helix_auth_method": ""
        }
      ]
    }

### GET /users/:id

Returns a single user.

#### Example request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/users/norris

#### Example response

    {
      "api_status": 200,
      "api_timestamp": "2019-10-24T14:03:48Z",
      "id": "norris",
      "created_at": "2019-10-24T14:03:48Z",
      "updated_at": "2019-10-24T14:03:48Z",
      "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "type": "user",
      "email": "chuck.norris@company.com",
      "short_name": "cnorris",
      "first_name": "Chuck",
      "last_name": "Norris",
      "display_name": "Chuck Norris",
      "company_admin": true,
      "instance_admin": true,
      "description": "Walker Texas Ranger",
      "phone": "",
      "title": "Executive Executor",
      "avatar": {
        "api_status": 200,
        "api_timestamp": "2019-10-24T14:03:48Z",
        "id": "YYYYYY-YYYY-YYYY-YYYY-YYYYYYYY",
        "created_at": "2019-10-24T14:03:48Z",
        "updated_at": "2019-10-24T14:03:48Z",
        "large": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-100x100.jpg",
        "medium": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-60x60.jpg",
        "small": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-30x30.jpg"
      },
      "synchronized_fields": [
        "short_name"
      ],
      "locale": "en",
      "source": ""
      "last_login_at": "2019-10-24T14:03:53Z",
      "login_count": 1,
      "password_given": true,
      "password_changed_at": null,
      "password_expires_at": null,
      "password_expired": false,
      "password_never_expires": false,
      "helix_auth_method": ""
    }

### GET /users/:id/projects

Returns a list of projects the user belongs to.

#### Example request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/users/norris/projects

#### Example response

    {
      "metadata": {
        "more_results": false,
        "next_offset": 2,
        "count": 2
      },
      "results":[
        {
          "api_status"200,
          "api_timestamp":"2020-09-15T09:03:37Z",
          "id":"atomic_atom",
          "created_at":"2020-09-10T13:07:42Z",
          "updated_at":"2020-09-10T13:07:42Z",
          "uuid":"6f3bf15f-486f-4710-ae8c-610d1335688f",
          "short_name":"atomic_atom",
          "name":"Atomic Atom",
          "description":"",
          "color":"blue",
          "visibility":"members",
          "labels":[

          ],
          "properties":{

          },
          "default_repository_authorization_enabled":false,
          "automatic_depot_creation":false,
          "depot":null,
          "hook_events":[
            "repository"
          ],
          "has_wiki":false
        },
        {
          <other projects the user is a member of, formatted as above>
        }
      ]
    }

### POST /users

Creates a new user to the company and returns the created user object. A matching user is first searched from the directory (by `email` and `id`) when LDAP authentication is enabled. The user must be found from the directory when LDAP only authentication is used, otherwise a 404 response is returned.

#### Example request

    curl -X POST \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "first_name": "Clark", "last_name": "Kent", "id":"ckent", "email": "clark.kent@company.com", "password": "Clar!Ken7" }' \
      https://helixteamhub.cloud/api/users

#### Example response

    {
      "api_status": 201,
      "api_timestamp": "2019-10-24T14:03:48Z",
      "id": "ckent",
      "created_at": "2019-10-24T14:03:48Z",
      "updated_at": "2019-10-24T14:03:48Z",
      "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "type": "user",
      "email": "clark.kent@company.com",
      "short_name": "ckent",
      "first_name": "Clark",
      "last_name": "Kent",
      "display_name": "Clark Kent",
      "company_admin": false,
      "instance_admin": false,
      "description": "",
      "phone": "",
      "title": "",
      "avatar":{
        "api_status": 201,
        "api_timestamp": "2019-10-24T14:03:48Z",
        "id": "",
        "created_at": "",
        "updated_at": "",
        "large": "",
        "medium": "",
        "small": ""
      },
      "synchronized_fields": [],
      "locale": "en",
      "source": "external"
      "last_login_at": null,
      "login_count": 0,
      "password_given": true,
      "password_changed_at": null,
      "password_expires_at": null,
      "password_expired": false,
      "password_never_expires": false,
      "helix_auth_method": ""
    }

### PUT /users/:id

Updates a the information of a single user. Returns the updated user object.

#### Example request

    curl -X PUT \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "description": "Retired" }' \
      https://helixteamhub.cloud/api/users/norris

#### Example response

    {
      "api_status": 200,
      "api_timestamp": "2019-10-24T14:03:48Z",
      "id": "norris",
      "created_at": "2019-10-24T14:03:48Z",
      "updated_at": "2019-10-24T14:03:48Z",
      "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "type": "user",
      "email": "chuck.norris@company.com",
      "short_name": "cnorris",
      "first_name": "Chuck",
      "last_name": "Norris",
      "display_name": "Chuck Norris",
      "company_admin": true,
      "instance_admin": true,
      "description": "Retired",
      "phone": "",
      "title": "Executive Executor",
      "avatar": {
        "api_status": 200,
        "api_timestamp": "2019-10-24T14:03:48Z",
        "id": "YYYYYY-YYYY-YYYY-YYYY-YYYYYYYY",
        "created_at": "2019-10-24T14:03:48Z",
        "updated_at": "2019-10-24T14:03:48Z",
        "large": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-100x100.jpg",
        "medium": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-60x60.jpg",
        "small": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-30x30.jpg"
      },
      "synchronized_fields": [
        "short_name"
      ],
      "locale": "en",
      "source": ""
      "last_login_at": "2019-10-24T14:03:53Z",
      "login_count": 1,
      "password_given": true,
      "password_changed_at": null,
      "password_expires_at": null,
      "password_expired": false,
      "password_never_expires": false,
      "helix_auth_method": ""
    }

### DELETE /users/:id

Deletes a user. Returns the deleted user object.

#### Example request

    curl -X DELETE \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/users/norris

#### Example response

    {
      "api_status": 200,
      "api_timestamp": "2019-10-24T14:03:48Z",
      "id": "norris",
      "created_at": "2019-10-24T14:03:48Z",
      "updated_at": "2019-10-24T14:03:48Z",
      "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "type": "user",
      "email": "chuck.norris@company.com",
      "short_name": "cnorris",
      "first_name": "Chuck",
      "last_name": "Norris",
      "display_name": "Chuck Norris",
      "company_admin": true,
      "instance_admin": true,
      "description": "Walker Texas Ranger",
      "phone": "",
      "title": "Executive Executor",
      "avatar": {
        "api_status": 200,
        "api_timestamp": "2019-10-24T14:03:48Z",
        "id": "YYYYYY-YYYY-YYYY-YYYY-YYYYYYYY",
        "created_at": "2019-10-24T14:03:48Z",
        "updated_at": "2019-10-24T14:03:48Z",
        "large": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-100x100.jpg",
        "medium": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-60x60.jpg",
        "small": "system/uploads/d2641ea3-ba02-43a6-8566-bff3493c6bbc-30x30.jpg"
      },
      "synchronized_fields": [
        "short_name"
      ],
      "locale": "en",
      "source": ""
      "last_login_at": "2019-10-24T14:03:53Z",
      "login_count": 1,
      "password_given": true,
      "password_changed_at": null,
      "password_expires_at": null,
      "password_expired": false,
      "password_never_expires": false,
      "helix_auth_method": ""
    }

### GET /users/count

Returns an object containing the amounts of total, active, and inactive users in the company.

#### Example request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/users/count

#### Example response

    {
      "api_status": 200,
      "api_timestamp": "2020-01-24T15:38:00Z",
      "count": 175,
      "active": 119,
      "inactive": 56
    }

Your search for returned results

Your search for returned results