Users Management

Users Basics

Get details for multiple users

GET /users/multiple/(string: userIds)

Retrieve all the information that Horn knows about the users listed in the userIds parameter

Parameters:

  • userIds (string) – A comma separated list of user ID’s e.g. 134,140

Query Parameters:

  • imgSize (string)

Response JSON Object:

  • followedBy (boolean) – [default: false] True if the authenticated user is followed by the authenticated user

  • reputation (int) – Reputation score

  • clientId (string) – Client id that user belongs to

  • description (option[string]) – A brief text description provided by the user

  • fullName (option[string]) – A full name provided by the user

  • following (boolean) – [default: false] True if the authenticated user is following this user

  • urlHandle (option[string]) – The user’s handle with switched chars to more url friendly

  • id (long) – The user’s unique ID

  • languages (option[languages]) – [default: None] Ordered list with languages and string for Accept-Language header

  • unregistered (boolean) – [default: false] True if the user is an unregistered user/temporary

  • authKind (option[userauthkind.value]) – [default: None] What kind of authorization will this user use (oAuth, Custom Auth etc). Guests don’t have this attribute at all

  • kind (userkind.value) – Kind enumeration

  • imageUrl (option[string]) – A url pointing to the user’s image

  • handle (string) – The user’s handle

Get own user details

GET /users/me

Fetch publicly available information about a request owner.

Query Parameters:

  • imgSize (string)

Response JSON Object:

  • followedBy (boolean) – [default: false] True if the authenticated user is followed by the authenticated user

  • reputation (int) – Reputation score

  • clientId (string) – Client id that user belongs to

  • description (option[string]) – A brief text description provided by the user

  • fullName (option[string]) – A full name provided by the user

  • following (boolean) – [default: false] True if the authenticated user is following this user

  • urlHandle (option[string]) – The user’s handle with switched chars to more url friendly

  • id (long) – The user’s unique ID

  • languages (option[languages]) – [default: None] Ordered list with languages and string for Accept-Language header

  • unregistered (boolean) – [default: false] True if the user is an unregistered user/temporary

  • authKind (option[userauthkind.value]) – [default: None] What kind of authorization will this user use (oAuth, Custom Auth etc). Guests don’t have this attribute at all

  • kind (userkind.value) – Kind enumeration

  • imageUrl (option[string]) – A url pointing to the user’s image

  • handle (string) – The user’s handle

Get user client

GET /users/me/client

Fetch basic information about client that requesting user belongs to.

Response JSON Object:

  • id (string) – Client identifier

  • name (string) – Client name

  • disabled (option[boolean]) – If true, service is disabled for this client (and all its children)

Get user details

GET /users/(number: userId)

Fetch publicly available information about a request owner. This call can only be made by users with the Partner Admin role, and will only work when made for a clientId that is a child account of the partner’s clientId.

Parameters:

  • userId (number)

Query Parameters:

  • for_client (string) – Specifies client context for which request will be executed.

  • imgSize (string)

Response JSON Object:

  • followedBy (boolean) – [default: false] True if the authenticated user is followed by the authenticated user

  • reputation (int) – Reputation score

  • clientId (string) – Client id that user belongs to

  • description (option[string]) – A brief text description provided by the user

  • fullName (option[string]) – A full name provided by the user

  • following (boolean) – [default: false] True if the authenticated user is following this user

  • urlHandle (option[string]) – The user’s handle with switched chars to more url friendly

  • id (long) – The user’s unique ID

  • languages (option[languages]) – [default: None] Ordered list with languages and string for Accept-Language header

  • unregistered (boolean) – [default: false] True if the user is an unregistered user/temporary

  • authKind (option[userauthkind.value]) – [default: None] What kind of authorization will this user use (oAuth, Custom Auth etc). Guests don’t have this attribute at all

  • kind (userkind.value) – Kind enumeration

  • imageUrl (option[string]) – A url pointing to the user’s image

  • handle (string) – The user’s handle

Get user email

GET /users/(string: userId)/email

Get the user’s email address

Parameters:

  • userId (string)

List users

GET /users

Method that allows you to list users with Access Control Levels assigned to them. This method is available for users with any role in given context including channel owners and operators.

Query Parameters:

  • for_client (string) – If specified, executes call in the context of the identified clientId, which must be a child account of calling user’s client. (Partner Admins only)

  • search (string) – String to filter users handles/names by

  • limit (string) – Limit amount of results. Needed for implementing pagination

  • offset (string) – Offset at which start looking for results in database. Needed for implementing pagination

  • imgSize (string) – Optionally images size for users avatar images results

  • sort (string) – By what column sort results. Possible values: [“handle”, “level”]. Default is “level”

  • order (string) – In which order sort results. Possible values: [“asc”, “desc”]. Default is “desc”

  • levels (string) – Comma separated list of Access Levels identifiers to filter results by (i.e. “levels=3,4” to see only users that have assigned at least one of )

Response:

{
    total: number
    results: list
}

where total is a total amount of elements matching criteria results objects has following fields:

{
    levels: seq[accesslevel]  // List of access levels this user has
    id: long  // The user's unique ID
    authKind: option[userauthkind.value]  // What kind of authentication this user is using
    kind: userkind.value  // Kind enumeration
    invitationExpiry: option[long]  // Optional field that says when a pending invitation will expire for that usr. This makes sense only for predefined users.
    imageUrl: option[string]  // A url pointing to the user's image
    handle: string  // The user's handle
}

Remove users avatar

DELETE /users/(string: userId)/image

Allows to remove a Users Profile Image.

Parameters:

  • userId (string)

Set the user’s description

POST /users/(string: userId)/description

Update the user’s description text

Parameters:

  • userId (string)

Request JSON Object:

  • description (option[string]) – Description text

Set the user’s full name

POST /users/(string: userId)/fullname

Update the user’s full name field.

Parameters:

  • userId (string)

Request JSON Object:

  • fullName (option[string]) – Users full name

Set user email

POST /users/(string: userId)/email

Set the user’s email address and initiate verification of the address by sending a verification code to the email provided in the body. The recipient of the email should then either click on the link provided or extract the verfication code and call the “Verify Email Code” call. If a user attempts to set several different email addresses, the first email address to be validated will be accepted.

Parameters:

  • userId (string)

Request JSON Object:

  • email (option[string]) – User email to be set

Set user handle

POST /users/(string: userId)/handle

Can be used only for non registered users or when uniqueness of handles on client level is disabled. An unregistered (i.e. guest) user may change their name using this function. Unlike registered users, there is no need for unregistered user display names to be unique, Note: Calling this method for a registered user will not fail, but also will not do anything. Returns HTTP 200 if successful.

Parameters:

  • userId (string)

Request JSON Object:

  • handle (string) – User handle

Set user handle (with nonce)

POST /users/me/handle/(string: nonce)

A user may change their display name (“handle”) using this function. The caller should first reserve a name using the “Reserve Handle” call. The reservation token from that request should be used in this request.

Parameters:

  • nonce (string) – The reservation token obtained using the “Reserve handle” call

Set users avatar

POST /users/(string: userId)/image

Update the user’s image. If a URL is specified as the query parameter url then the image will be downloaded from the URL. If this parameter is not present, the request must contain the image in the body of the request. Images are limited in size to 8Mbytes. A URL takes precedence over an image in the request body.

Parameters:

  • userId (string)

Query Parameters:

  • url (string) – A URL specifying where the image may be downloaded. It must be specified if the image is not specified in the body of the request.

Verify email address

POST /users/email/verify/(string: code)

This is second step for email verification process.

Parameters:

  • code (string) – Code to be verified by.

Creating Users

Check handle uniqueness

GET /users/handle/unique

In Horn, user handles need to be unique. This function simply checks if a handle is unique or not. Use Reserve Handle to ensure that the handle requested will be available when the user is registered.

Query Parameters:

  • for_client (string) – If specified, executes call in the context of the identified clientId, which must be a child account of calling user’s client. (Partner Admins only)

  • handle (string) – A utf-8 formatted string containing the handle to be checked

Response JSON Object:

  • unique (boolean) – Boolean indicating whether is unique.

  • required (option[boolean]) – [default: None] Boolean indicating whether uniqunes is required in client

Create guest user

POST /clients/(string: clientId)/users/guest/(string: uuid)

Create a new temporary user.

Parameters:

  • clientId (string) – Specifies the client that user will be created for

  • uuid (string) – Channel ID

Request JSON Object:

  • handle (string) – User handle

Response JSON Object:

  • token (string) – The user’s secret token

  • expires (long) – The ttl of token

Create predefined user

POST /users/predefined

A “predefined” user is a stub of a user account that can be given access (roles), and can have other user details (name, etc.) defined, but that has not yet been connected to an authorization mechanism. Predefined users can be given invitation codes to let users join and attach authentication details to the account stub, or alternatively can be referenced by an idToken used in a “frictionless” custom authentication integration. To create predefined user accounts that will be accessed via custom auth integration, include the optional originId field in the request payload. The originId field will be used to associate idTokens passed in through the cuatom auth integration with the user account. If the originId field is not defined for a predefined user, the user will be prompted to choose an oAuth provider from the list of enabled providers in this client context.

Query Parameters:

  • for_client (string) – If specified, executes call in the context of the identified clientId, which must be a child account of calling user’s client. (Partner Admins only)

Request JSON Object:

  • name (string) – User name

  • email (option[string]) – User email address

  • description (option[string]) – Description text

  • imageUrl (option[string]) – url for image host by 3rd party service

  • originId (option[string]) – Id of this user in 3rd party IDP system

Response JSON Object:

  • id (long) – The User id

Create regular user

POST /users/create/(string: token)
Parameters:

  • token (string) – The handle reservation token requested using “Reserve Handle” call

Request JSON Object:

  • description (option[string]) – Description text

  • fullName (option[string]) – Users full name

  • email (option[string]) – User email address

  • imageUrl (option[string]) – url for image host by 3rd party service

Response JSON Object:

  • id (long) – The User id

Generate invitation

POST /users/(number: userId)/invitation

Generates (or re-generates) and returns a new invitation code for a pre-defined user. A user can have only one invitation code at a time, so calling this method has the side-effect of removing and invalidating any codes that already exist. This method is only meaningful for pre-defined users.

Parameters:

  • userId (number) – Identifier of a pre-defined user

Query Parameters:

  • for_client (string) – If specified, executes call in the context of the identified clientId, which must be a child account of calling user’s client. (Partner Admins only)

  • ttl (string) – Optional expiration interval for the new code. Specified as a number and a unit, e.g. “1m” for 1 minute, “1d” for one day, etc. If not provided, the default expiry interval will be used.

Response JSON Object:

  • userId (long) – Id of user

  • code (string) – Invitation code

  • expires (option[long]) – Expiration timestamp

  • kind (invitationkind.value) – Kind enumeration: Nonce - can be used only once, Persistent - JWT that can be exchanged to a horn token

Get predefined user ID

GET /users/predefined/(string: originId)

Looks for a predefined user account from 3rd party customer integration and returns Horn’s id for this user or 404 status in case user is not in Horn system yet. That method is only available for API token.

Parameters:

  • originId (string) – The ID of the user to check. This should be an ID in customer system

Response JSON Object:

  • id (long) – The User id

Get user invitation

GET /users/(number: userId)/invitation

Return any pending invitation for the specified user. The invitation can be used to generate a special link that can be used to connect authentication information to a pre-defined user and complete the account creation process. This call only returns any invitation that already exists. To create an invitiation in the first place, see Generate Invitation. This call is only meaningful for “pre-defined” users.

Parameters:

  • userId (number) – ID of a pre-defined user

Query Parameters:

  • for_client (string) – If specified, executes call in the context of the identified clientId, which must be a child account of calling user’s client. (Partner Admins only)

Response JSON Object:

  • userId (long) – Id of user

  • code (string) – Invitation code

  • expires (option[long]) – Expiration timestamp

  • kind (invitationkind.value) – Kind enumeration: Nonce - can be used only once, Persistent - JWT that can be exchanged to a horn token

Get user origin ID

GET /users/(number: userId)/originId

Returns originId (ID in customer system) that was used when predefining a user, or was returned in authentication flow by an authenticator.

Parameters:

  • userId (number) – The ID of the user to check.

Response JSON Object:

  • originId (string)

Reserve handle

POST /users/handle/reserve

Make a short term reservation for a “handle” (user display name). This function returns a token which can be used to register a user with the reserved handle or alternatively change their current handle. The reservation will last for 15 minutes.

Request JSON Object:

  • handle (string) – User handle

Response JSON Object:

  • reservationToken (string) – A Token which give right to use associated handler

User Properties

Delete user properties

DELETE /users/(string: userId)/properties/(string: key)

Allows to delete properties tied to a user

Parameters:

  • userId (string) – Me or user id

  • key (string) – The property key

Get user properties

GET /users/(string: userId)/properties/(string: key)

Allows to get arbitrary properties tied to a user, it can persist various kinds of custom state and/or data that are relevant to third party integrations. When requesting a properties the value will be return as a JSON in the response body.

Parameters:

  • userId (string) – Me or user id

  • key (string) – The property key

Response: JSON

List user properties

GET /users/(string: userId)/properties

Allows to list all keys of properties tied to a user

Parameters:

  • userId (string)

Set user properties

POST /users/(string: userId)/properties/(string: key)

Allows to set arbitrary properties tied to a user, it can persist various kinds of custom state and/or data that are relevant to third party integrations. Value for the property should be send as a json in the request body. The call will accept any json, save it under given key and allow to fetch it back.

Parameters:

  • userId (string) – Me or user id

  • key (string) – The property key

Request: JSON

Other

Configure if users handle uniqueness is required

POST /settings/users/handle/unique/(string: state)
Parameters:

  • state (string) – Can be one of enable/disable

Get a list of supported languages

GET /users/languages

Return a list of supported languages. Horn is largely language agnostic so the supported languages are really just a guide.

Get user ID by handle

GET /users/handle/get

Look up a user’s identity from their handle. User’s can change their handles at any time but their ID will remain constant.

Query Parameters:

  • handle (string) – The user’s handle to look up.

Response JSON Object:

  • id (long) – The User id

Get user by email

GET /users/email/search

Method that allows you to find a user Id by an email address

Query Parameters:

  • email (string)

Response JSON Object:

  • id (long) – The User id

Set guest user handle

POST /channels/(string: uuid)/users/(number: userId)/rename

The “handle” is the visible username of a user in a channel. This method lets a host set the handle of unregistered users (guests and dial-in/dial-out users).

Parameters:

  • uuid (string) – The channel ID in which the change will occur

  • userId (number) – The ID of a user to rename

Request JSON Object:

  • handle (string) – User handle

Set the user’s preferred language

POST /users/(string: userId)/languages

Set the preferred language. Languages are specified as an ISO 639-1 code with an optional region specifier. Examples are en-in, ar and es. The preferred languages can be obtained from the browser’s internationalization information.

Parameters:

  • userId (string)

Request JSON Object:

  • languages (seq[string]) – Ordered list with languages codes