Hiyllo API

Official JS package for working with Hiyllo services.

Introducton

Every organization that signs up to Hiyllo for Business is treated as its own isolated federation. Users that are created under the organization are sioled to that organization.

Each federation has a slug that is chosen when signing up. You can see your slug by checking in your Hiyllo Business URL when logged in <federation slug>.hiyllo.business.

Every user is given a hiylloID. While users cannot interact across fedrations, this Hiyllo ID is guaranteed to be unique across the entire Hiyllo platform.

Creating an API Key

To create an API key, head to your organization's Hiyllo Business dashboard, click "API" in the top right corner, then follow the instructions to generate your key.

Environment and Compatability

@hiyllo/api is compiled to ES5 with NodeJS module resolution. It's only external dependency is axios which is used to communicate with Hiyllo's servers.

Usage

const hiylloAPI = new HiylloAPI("yourapikeyhere");

The HiylloAPI class and its methods are fully typed and JSdoc documented.

Federated Users

Create Federated User (hiylloAPI.createUser)

interface Request {
    returnPath: string; // <- URL the user is directed to after they complete federation signup
    email: string, // <- email of the new user
    username: string, // <- username of the new user. Must be unique across your federation
}

interface Response { 
    hiylloID: string;
}

const response = await hiylloAPI.createUser(request);

Delete Federated User (hiylloAPI.deleteUser)

This action is permanent. All data for that user will be deleted. However their username will remain blocked and unavailable permanently. If you need to reuse the username of a deleted user, you can engage the transfer username procedure. Contact Hiyllo support for details.

Organization superadmin users cannot be deleted via the API.

interface Request {
    hiylloID: string;
}

interface Response { 
    // Empty
}

const response = await hiylloAPI.deleteUser(request);

Get Federated User by Email (hiylloAPI.getUserByEmail)

interface Request {
    email: string;
}

interface HiylloUserType {
    username: string;
    hiylloID: string;
    email: string;
    isFederationAdmin: boolean;
}

interface Response {
    user: HiylloUserType | null;
}

const response = await hiylloAPI.getUserByEmail(request);

Get Federated User by HiylloID (hiylloAPI.getUserByHiylloID)

interface Request {
    hiylloID: string;
}

interface HiylloUserType {
    username: string;
    hiylloID: string;
    email: string;
    isFederationAdmin: boolean;
}

interface Response {
    user: HiylloUserType | null;
}

const response = await hiylloAPI.getUserByHiylloID(request);

Hiyllo Work

These methods require an existing Hiyllo Work workspace. Once you have the workspace, identify the workspace's "slug" (the part before .hiyllo.work, e.g. if URL is acme.hiyllo.work your slug is acme).

Add User to Workspace (hiylloAPI.workspaces.addUserToWorkspace)

interface Request {
    hiylloID: string, // <- HiylloID of the existing federated user (see above)
    workspaceSlug: string, // <- Slug of the workspace
    managerId: string, // <- HiylloID of the federated user who manages this user [^1]
    title: string, // <- Title of the user
    grantAdmin: boolean, // <- Whether to grant the user workspace admin [^2]
}

interface Response {
    // Empty
}

const response = await hiylloAPI.workspaces.addUserToWorkspace(request);

[^1]: Users created via the API must have managers. To create a user without a manager use the Hiyllo Work UI. [^2]: Workspace admins can only administrate that specific workspace. They cannot access things like organization billing or API keys, but they can add new users (which can have billing impacts).

Remove User from Workspace (hiylloAPI.workspaces.removeUserFromWorkspace)

Removes a user from a Hiyllo Work (www.hiyllo.work) workspace.

This is a permanent operation. All data for that user on the workspace will be deleted. Their organization account will not be affected.

[Billing Impact] Removing users from a workspace will decrease the number of users on the workspace. This may impact the cost of your workspace subscription.

interface Request {
    hiylloID: string, // <- HiylloID of the user you want to add
    workspaceSlug: string, // <- Slug of the workspace
}

interface Response {
    // Empty
}

const response = await hiylloAPI.workspaces.removeUserFromWorkspace(request);

Create Team (hiylloAPI.workspaces.createTeam)

interface Request {
    name: string, // <- Name of your new team
    workspaceSlug: string, // <- Slug of the workspace
    manager: string | null, // <- HiylloID of the team's manager
}

interface Response {
    uuid: string, // <- UUID of your new team
}

const response = await hiylloAPI.workspaces.createTeam(request);

Delete Team (hiylloAPI.workspaces.deleteTeam)

interface Request {
    uuid: string, // <- UUID of the team you want to delete
    workspaceSlug: string, // <- Slug of the workspace
}

interface Response {
    // Empty
}

const response = await hiylloAPI.workspaces.createTeam(request);

Get Team (hiylloAPI.workspaces.getTeam)

interface Request {
    uuid: string; // <- UUID of the team you want to get
    workspaceSlug: string, // <- Slug of the workspace
}

interface Response {
    team: {
        name: string;
    }
    members: Array<{ hiylloID: string; }>
}

const response = await hiylloAPI.workspaces.getTeam(request);

Add User to Team (hiylloAPI.workspaces.addUserToTeam)

interface Request {
    hiylloID: string, // <- HiylloID of the user you want to add
    teamUUID: string, // <- UUID of the team you want to delete
    workspaceSlug: string, // <- Slug of the workspace
}

interface Response {
    // Empty
}

const response = await hiylloAPI.workspaces.addUserToTeam(request);

Get Project (hiylloAPI.workspaces.getProject)

export interface TasksProject {
    name: string;
    description: string;
    tags: string[];
    uuid: string;
}

interface Request {
    uuid: string,
    workspaceSlug: string // <- Slug of the workspace
}

interface Response {
    project: TaskProject
}

const response = await hiylloAPI.workspaces.getProject(request);

Get Projects With Tag (hiylloAPI.workspaces.getProjectsWithTag)

export interface TasksProject {
    name: string;
    description: string;
    tags: string[];
    uuid: string;
}

interface Request {
    tag: string,
    workspaceSlug: string // <- Slug of the workspace
}

interface Response {
    projects: TasksProject[]
}

const response = await hiylloAPI.workspaces.getProjectsWithTag(request);

Patch (Update) Project (hiylloAPI.workspaces.patchProject)

Patch update a given Project

interface Request {
    uuid: string,
    workspaceSlug: string,
    patch: Partial<{
        name: string;
        description: string;
        tags: { $add: string; } | { $remove: string; };
    }>
}

interface Response {
    // Empty
}

const response = await hiylloAPI.workspaces.patchProject(request);