Account Settings - Huddle/huddle-apis GitHub Wiki

Summary

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

All paths below are under the /membership virtual path (reverse proxy / gateway mapping in deployment). The Membership service mounts these routes at /accounts/...; clients should use /membership/accounts/....

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.
On-demand reports for an account are documented in Create ODR Report (listed in the wiki sidebar under Membership → Accounts).

Operations

Method	Path	Purpose	Details
`GET`	`/membership/accounts/{accountId}/settings`	Retrieve an Account Settings - Overview	Jump
`GET`	`/membership/accounts/{accountId}/settings/editable`	Retrieve an Editable Account Settings - Overview	Jump
`PUT`	`/membership/accounts/{accountId}/settings/editable`	Update an Account Settings - Overview	Jump
`GET`	`/membership/accounts/{accountId}/settings/workspaces`	Retrieve an Account Settings - Workspaces	Jump
`GET`	`/membership/accounts/{accountId}/settings/workspaces/{workspaceId}/editable`	Retrieve an Editable Account Settings - Workspace	Jump
`PUT`	`/membership/accounts/{accountId}/settings/workspaces/{workspaceId}/editable`	Update an Account Settings - Workspace Settings	Jump
`PUT`	`/membership/accounts/{accountId}/settings/workspaces/{workspaceId}/status`	Update an Account Settings - Workspace Status	Jump
`PUT`	`/membership/accounts/{accountId}/settings/workspaces/{workspaceId}/finalise`	Finalise Workspace in Account Settings	Jump
`DELETE`	`/membership/accounts/{accountId}/settings/workspaces/{workspaceId}`	Delete Workspace in Account Settings	Jump
`POST`	`/membership/accounts/{accountId}/settings/workspaces/{workspaceId}/manager/add`	Add Account Manager as Workspace Manager in Account Settings	Jump

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 /membership/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 /membership/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,
    "logInExpiryTimeEnabled": 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 /membership/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: /membership/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 /membership/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
}

Each entry in workspaces includes only the links that apply for that workspace and the authenticated account manager (for example update-status only if the status may be changed, finalise only when the workspace can be finalised, add-managers only when the actor may add themselves as a workspace manager, and edit / delete only when those actions are allowed).

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 for the authenticated account manager to add themselves as a workspace manager.	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 /membership/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 /membership/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

{
    "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 for the authenticated account manager to add themselves as a workspace manager.	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 /membership/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

{
 "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 for the authenticated account manager to add themselves as a workspace manager.	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 /membership/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

{
 "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 for the authenticated account manager to add themselves as a workspace manager.	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 /membership/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

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 account manager as workspace manager

Adds the authenticated account manager as a workspace manager for the given workspace. There is no request body.

Example

The following example requests for add a workspace manager into workspace with ID 456 and under an Account with ID 123 by User which is Account Manager.

Request:

POST /membership/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

{
 "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 for the authenticated account manager to add themselves as a workspace manager.	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
Invalid user Id	404 Not Found