Account Settings (Pre alpha) - Huddle/huddle-apis GitHub Wiki

Note

The APIs for Account Settings haven't been released to live environment and not ready to be used.

Summary

The Membership Account Settings API is a representation of a given Account Settings within Huddle.

  • The Account Settings API can be called by Account Manager only. Unauthorised users to call this endpoint are Admin, Company Manager, Workspace Manager, Workspace Member and Non-Workspace Member. Refer here for permission matrix.

Table of contents

Operation
Retrieve an Account Settings - Overview
Retrieve an Editable Account Settings - Overview
Update an Account Settings - Overview
Retrieve an Account Settings - Workspaces
Retrieve an Editable Account Settings - Workspace
Update an Account Settings - Workspace Settings
Update an Account Settings - Workspace Status
Finalise Workspace in Account Settings
Delete Workspace in Account Settings
Add Account Managers as Workspace Managers in Account Settings
Modify the branding logo

Operations

Retrieve an Account Settings - Overview

You can GET a given Account Settings overview of an Account by its ID.

Example

The following example requests account settings overview of an Account with ID 123.

Request:

GET /accounts/123/settings HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
    "status": "0",
    "package": "Package_FreeTrial",
    "createdDate": "2022-07-28T07:39:40.177",
    "domain": "my.huddle.net",
    "noOfActiveWorkspaces": "1",
    "noOfUsersInWorkspaces": "1",
    "anyOneCanCreateWorkspaces": "true",
    "noOfUserLimit": "1000000",
    "loginExpiryTimeInMinute": "0",
    "links": [
        { "rel" : "self", "href": "..." },
        { "rel" : "parent", "href": "..." },
        { "rel" : "update ", "href": "..." } 
    ]
}

Response Properties

Name Description
Account Settings Overview The account settings overview resource

Response Link relations

Name Description Methods
self The URI of this account settings overview. GET
parent The URI of the account that account settings overview belongs to. GET
update The URI to get the editable account settings overview. GET

Other Responses

Case Response
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Account does not exist 404 Not Found

Retrieve Editable Account Settings - Overview

You can GET editable Account Settings overview of an Account by its ID.

Example

The following example requests editable account settings overview of an Account with ID 123.

Request:

GET /accounts/123/settings/editable HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
    "anyOneCanCreateWorkspaces": "true",
    "loginExpiryTimeInMinute ": "0",
    "logInExpiryTimeInEnabled": "false",
    "links": [
        { "rel" : "self", "href": "..." },
        { "rel" : "parent", "href": "..." },
        { "rel" : "update ", "href": "..." } 
    ]
}

Response Properties

Name Description
Account Settings Overview The editable fields of account settings overview, and their current values

Response Link relations

Name Description Methods
self The URI of this editable account settings overview. GET
parent The URI of the account settings overview. GET
update The URI to update account settings overview. PUT

Other Responses

Case Response
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Account does not exist 404 Not Found

Update Account Settings - Overview

To update account settings first retrieve editable account settings overview to show which account settings overview can be updated. Then, to update them, make a call to the update account settings endpoint.

Example

The following example requests for update account settings overview of an Account with ID 123.

Request Payload Description

Field Data Type Example
anyOneCanCreateWorkspaces Boolean True or False
loginExpiryTimeInMinute Integer Only integer without decimals

Request:

PUT /accounts/123/settings/editable HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
    "anyOneCanCreateWorkspaces ": "false"
    "loginExpiryTimeInMinute ": "10"
}

Response:

If successful, this method will return with a 200 OK status code. The response body will be the updated account settings overview.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /accounts/123/settings

{
    "status": "0",
    "package": "Package_FreeTrial",
    "createdDate": "2022-07-28T07:39:40.177",
    "domain": "my.huddle.net",
    "noOfActiveWorkspaces": "1",
    "noOfUsersInWorkspaces": "1",
    "anyOneCanCreateWorkspaces": "false",
    "noOfUserLimit": "1000000",
    "loginExpiryTimeInMinute": "10",
    "links": [
        { "rel" : "self", "href": "..." },
        { "rel" : "parent", "href": "..." },
        { "rel" : "update ", "href": "..." } 
    ]
}

Response Properties

Name Description
Account Settings Overview The account settings overview resource

Response Link relations

Name Description Methods
self The URI of this account settings overview. GET
parent The URI of the account that account settings overview belongs to. GET
update The URI to get the editable account settings overview. GET

Other Responses

Case Response
Invalid login expiry time 400 Bad Request
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Account does not exist 404 Not Found

Retrieve an Account Settings - Workspaces

You can GET a given Account Settings workspaces of an Account by its ID.

Example

The following example requests account settings workspaces of an Account with ID 123.

Request:

GET /accounts/123/settings/workspaces HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
    "links" : [{
      "rel" : "self",
      "href" : "..."
    }],
    "workspaces" : [{
      "title" : "Workspace 1",
      "createdDate" : "2022-08-25T06:44:32.417",
      "status": 0,
      "workspaceUsersCount": 1,
      "workspaceManagersCount": 1,
      "links" : [
                      { "rel": "update-status","href": "..." },
		      { "rel": "finalise","href": "..." },
		      { "rel": "edit","href": "..." },
		      { "rel": "delete","href": "..." },
		      { "rel": "add-managers","href": "..." }
                ]
      },{
      "title" : "Workspace 2",
      "createdDate" : "2022-08-18T02:08:13.773",
      "status": 1,
      "workspaceUsersCount": 1,
      "workspaceManagersCount": 1,
      "links" : [
                      { "rel": "update-status","href": "..." },
		      { "rel": "finalise","href": "..." },
		      { "rel": "edit","href": "..." },
		      { "rel": "delete","href": "..." },
		      { "rel": "add-managers","href": "..." }
                ]
    }],
    "totalUsersInWorkspaces": 4,
    "totalActiveAndLockedWorkspaces": 2
}

Response Properties

Name Description
Account Settings Workspaces The account settings workspaces resource

Response Link relations

Name Description Methods
self The URI of this account settings workspaces. GET
edit The URI to get the editable workspace settings of a workspace from account settings. GET
update-status The URI to update the workspace status from account settings. PUT
finalise The URI to finalise the workspace from account settings. PUT
add-managers The URI to add user as workspace manager from account settings. POST
delete The URI to delete the workspace from account settings. DELETE

Other Responses

Case Response
Invalid account ID provided 400 Bad Request
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Account does not exist 404 Not Found

Retrieve Editable Account Settings - Workspace

You can GET an editable workspace settings of a workspace from an Account by its Workspace ID and Account ID.

Example

The following example requests for editable workspace settings of a Workspace with ID 124 and under an Account with ID 123.

Request:

GET /accounts/123/settings/workspaces/124/editable HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
    "invitationPriviledgeForAnybody": true,
    "title": "Workspace 1",
    "description": "This is a workspace",
    "links": [
        { "rel" : "self", "href": "..." },
        { "rel" : "parent", "href": "..." },
        { "rel" : "update ", "href": "..." } 
    ]
}

Response Properties

Name Description
Workspace Settings of a Workspace From Account Settings The editable fields of a workspace that belongs to an account, and their current values

Response Link relations

Name Description Methods
self The URI of this editable workspace settings that belongs to the account. GET
parent The URI of the account settings workspaces. GET
update The URI to update workspace settings of a workspace that belongs to the account. PUT

Other Responses

Case Response
Invalid account ID provided 400 Bad Request
Invalid workspace ID provided 400 Bad Request
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Account does not exist 404 Not Found
Workspace does not exist 404 Not Found
Workspace does not belongs to the Account 404 Not Found

Update Account Settings - Workspace Settings

To update workspace settings first retrieve editable workspace settings to show which workspace settings can be updated. Then, to update them, make a call to the update workspace settings endpoint.

Example

The following example requests to update workspace settings for workspace ID 124 of an Account with ID 123.

Request Payload Description

Field Data Type Required Example
invitationPriviledgeForAnybody Boolean Optional True or False
title String Required "Workspace 1"
description String Optional "This is a workspace"

Request:

PUT /accounts/123/settings/workspaces/124/editable HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
    "invitationPriviledgeForAnybody": true,
    "title": "Workspace 1",
    "description": "This is a workspace"
}

Response:

If successful, this method will return with a 200 OK status code. The response body will be the updated account settings workspaces.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /accounts/123/settings/workspaces

{
    "links" : [{
      "rel" : "self",
      "href" : "..."
    }],
    "workspaces" : [{
      "title" : "Workspace 1",
      "createdDate" : "2022-08-25T06:44:32.417",
      "status": 0,
      "workspaceUsersCount": 1,
      "workspaceManagersCount": 1,
      "links" : [
                      { "rel": "update-status","href": "..." },
		      { "rel": "finalise","href": "..." },
		      { "rel": "edit","href": "..." },
		      { "rel": "delete","href": "..." },
		      { "rel": "add-managers","href": "..." }
                ]
      },{
      "title" : "Workspace 2",
      "createdDate" : "2022-08-18T02:08:13.773",
      "status": 1,
      "workspaceUsersCount": 1,
      "workspaceManagersCount": 1,
      "links" : [
                      { "rel": "update-status","href": "..." },
		      { "rel": "finalise","href": "..." },
		      { "rel": "edit","href": "..." },
		      { "rel": "delete","href": "..." },
		      { "rel": "add-managers","href": "..." }
                ]
    }],
    "totalUsersInWorkspaces": 4,
    "totalActiveAndLockedWorkspaces": 2
}

Response Properties

Name Description
Account Settings Workspaces The account settings workspaces resource

Response Link relations

Name Description Methods
self The URI of this account settings workspaces. GET
edit The URI to get the editable workspace settings of a workspace from account settings. GET
update-status The URI to update the workspace status from account settings. PUT
finalise The URI to finalise the workspace from account settings. PUT
add-managers The URI to add user as workspace manager from account settings. POST
delete The URI to delete the workspace from account settings. DELETE

Other Responses

Case Response
Invalid account ID provided 400 Bad Request
Invalid workspace ID provided 400 Bad Request
Invalid workspace title 400 Bad Request
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Account does not exist 404 Not Found
Workspace does not exist 404 Not Found
Workspace does not belongs to the Account 404 Not Found

Update Account Settings - Workspace Status

To update workspace status to Locked or Active status from Account Settings within Huddle.

Example

The following example requests for update workspace status of a Workspace with ID 456 and under an Account with ID 123 by User which is Account Manager.

Request Payload Description

Field Data Type Example Remark
status String Active or Locked case sensitive

Request:

PUT /accounts/123/settings/workspaces/456/status HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
    "status ": "Active"
}

Response:

If successful, this method will return with a 200 OK status code. The response body will be the account settings workspaces.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /accounts/123/settings/workspaces/456/status

{
	"links": [ { "rel": "self", "href": "..." } ],
	"workspaces": [
		{
			"title": "workspaceA",
			"createdDate": "2022-08-26T09:53:24.19",
			"status": 1,
			"workspaceUsersCount": 1,
			"workspaceManagersCount": 1,
			"links": [
				{ "rel": "update-status","href": "..." },
				{ "rel": "finalise","href": "..." },
				{ "rel": "edit","href": "..." },
				{ "rel": "delete","href": "..." },
				{ "rel": "add-managers","href": "..." }
			]
		}
	],
	"totalUsersInWorkspaces": 1,
	"totalActiveAndLockedWorkspaces": 1
}

Response Properties

Name Description
Account Settings Workspaces The account settings workspaces resource

Response Link relations

Name Description Methods
self The URI of this account settings workspaces. GET
edit The URI to get the editable workspace settings of a workspace from account settings. GET
update-status The URI to update the workspace status from account settings. PUT
finalise The URI to finalise the workspace from account settings. PUT
add-managers The URI to add user as workspace manager from account settings. POST
delete The URI to delete the workspace from account settings. DELETE

Other Responses

Case Response
Invalid workspace status 400 Bad Request
Invalid account id 400 Bad Request
Invalid workspace id 400 Bad Request
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Account does not exist 404 Not Found
Workspace does not exist 404 Not Found

Account Settings - Finalise Workspace

To finalise workspace ( update the workspace status to Archived ) from Account Settings within Huddle.

Example

The following example requests for finalise workspace of a Workspace with ID 456 and under an Account with ID 123 by User which is Account Manager.

Request:

PUT /accounts/123/settings/workspaces/456/finalise HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response:

If successful, this method will return with a 200 OK status code. The response body will be the account settings workspaces.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /accounts/123/settings/workspaces/456/finalise

{
	"links": [ { "rel": "self", "href": "..." } ],
	"workspaces": [
		{
			"title": "workspaceA",
			"createdDate": "2022-08-26T09:53:24.19",
			"status": 1,
			"workspaceUsersCount": 1,
			"workspaceManagersCount": 1,
			"links": [
				{ "rel": "update-status","href": "..." },
				{ "rel": "finalise","href": "..." },
				{ "rel": "edit","href": "..." },
				{ "rel": "delete","href": "..." },
				{ "rel": "add-managers","href": "..." }
			]
		}
	],
	"totalUsersInWorkspaces": 1,
	"totalActiveAndLockedWorkspaces": 1
}

Response Properties

Name Description
Account Settings Workspaces The account settings workspaces resource

Response Link relations

Name Description Methods
self The URI of this account settings workspaces. GET
edit The URI to get the editable workspace settings of a workspace from account settings. GET
update-status The URI to update the workspace status from account settings. PUT
finalise The URI to finalise the workspace from account settings. PUT
add-managers The URI to add user as workspace manager from account settings. POST
delete The URI to delete the workspace from account settings. DELETE

Other Responses

Case Response
Invalid workspace status 400 Bad Request
Invalid account id 400 Bad Request
Invalid workspace id 400 Bad Request
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Account does not exist 404 Not Found
Workspace does not exist 404 Not Found

Account Settings - Delete Workspace

To delete workspace ( update the workspace status to Deleted ) from Account Settings within Huddle.

Example

The following example requests to delete workspace of a Workspace with ID 456 and under an Account with ID 123 by User which is Account Manager.

Request:

DELETE /accounts/123/settings/workspaces/456 HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response:

If successful, this method will return with a 204 No Content status code.

HTTP/1.1 204 No Content
Content-Type: application/vnd.huddle.data+json
Content-Location: /accounts/123/settings/workspaces/456

Other Responses

Case Response
Invalid workspace status 400 Bad Request
Invalid account id 400 Bad Request
Invalid workspace id 400 Bad Request
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Account does not exist 404 Not Found
Workspace does not exist 404 Not Found

Account Settings - Add you yourself (account manager) as workspace manager

To add you yourself (account manager) as workspace manager from Account Settings within Huddle.

Example

Request:

POST /accounts/123/settings/workspaces/456/manager/add HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response:

If successful, this method will return with a 200 OK status code. The response body will be the account settings workspaces.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /accounts/123/settings/workspaces/456/manager/add

{
	"links": [ { "rel": "self", "href": "..." } ],
	"workspaces": [
		{
			"title": "workspaceA",
			"createdDate": "2022-08-26T09:53:24.19",
			"status": 1,
			"workspaceUsersCount": 1,
			"workspaceManagersCount": 1,
			"links": [
				{ "rel": "update-status","href": "..." },
				{ "rel": "finalise","href": "..." },
				{ "rel": "edit","href": "..." },
				{ "rel": "delete","href": "..." },
				{ "rel": "add-managers","href": "..." }
			]
		}
	],
	"totalUsersInWorkspaces": 1,
	"totalActiveAndLockedWorkspaces": 1
}

Response Properties

Name Description
Account Settings Workspaces The account settings workspaces resource

Response Link relations

Name Description Methods
self The URI of this account settings workspaces. GET
edit The URI to get the editable workspace settings of a workspace from account settings. GET
update-status The URI to update the workspace status from account settings. PUT
finalise The URI to finalise the workspace from account settings. PUT
add-managers The URI to add user as workspace manager from account settings. POST
delete The URI to delete the workspace from account settings. DELETE

Other Responses

Case Response
Invalid workspace status 400 Bad Request
Invalid account id 400 Bad Request
Invalid workspace id 400 Bad Request
Empty User Ids 400 Bad Request
Invalid authorization token 401 Unauthorized
Actor is not an authorised user 403 Forbidden
Account does not exist 404 Not Found
Workspace does not exist 404 Not Found

Account Settings Customization - Modify the branding logo

To modify the branding logo for login-logo, dashboard-logo and default-workspace-logo. The APIs is only containing modify the database, for upload the logo need to proceed on File BC.

Example

The following example requests for modify the login-logo.

Request:

PUT /accounts/123/settings/customization/login-logo.jpg HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response:

If successful, this method will return with a 200 OK status code. The response body will be the account settings customization.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /accounts/123/settings/workspaces/456/managers/add

{
    "links": [
        {
            "rel": "self",
            "href": ".../membership/accounts/123/settings/customization"
        },
        {
            "rel": "membership-login-logo",
            "href": ".../membership/accounts/123/settings/customization/login-logo.jpg"
        },
        {
            "rel": "membership-dashboard-logo",
            "href": ".../membership/accounts/123/settings/customization/dashboard-logo.jpg"
        },
        {
            "rel": "membership-default-ws-logo",
            "href": ".../membership/accounts/123/settings/customization/default-ws-logo.jpg"
        },
        {
            "rel": "files-login-logo",
            "href": ".../files/accountsettings/123/customization/login-logo.jpg"
        },
        {
            "rel": "files-dashboard-logo",
            "href": ".../files/accountsettings/123/customization/dashboard-logo.jpg"
        },
        {
            "rel": "files-default-ws-logo",
            "href": ".../files/accountsettings/123/customization/default-ws-logo.jpg"
        }
    ]
}

Response Properties

Name Description
Account Settings Customization The account settings resource

Response Link relations

Name Description Methods
self The URI of this account settings customization GET
membership-login-logo The URI to update the version key on database PUT
membership-dashboard-logo The URI to update the version key on database PUT
membership-default-ws-logo The URI to update the version key on database PUT
file-login-logo The URI to receive the login-logo GET
file-dashboard-logo The URI to receive the dashboard-logo GET
file-default-ws-logo The URI to receive the default-workspace-logo GET
file-login-logo The URI to upload the login-logo PUT
file-dashboard-logo The URI to upload the dashboard-logo PUT
file-default-ws-logo The URI to upload the default-workspace-logo PUT
file-login-logo The URI to reset the login-logo DELETE
file-dashboard-logo The URI to reset the dashboard-logo DELETE
file-default-ws-logo The URI to reset the default-workspace-logo DELETE

Other Responses

Case Response
Invalid logo branding type 400 Bad Request
Invalid authorization token 401 Unauthorized
Branding reserved 403 Forbidden
Actor is not an authorised user 403 Forbidden
Account does not exist 404 Not Found