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
}