# Authentication ## Check JWT token #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/auth/check` | HTTP/S | GET | | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | ## Login user #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/auth/login` | HTTP/S | POST | | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | username | string | POST | Username | N/A | YES | | password | string | POST | Password | N/A | YES | ## Delete JWT token (Sign Out) #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/auth/logout` | HTTP/S | GET | | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | # Organisations Organisations represent a top-level grouping entity. There may be many organisations defined in a single deployment. ## List organisations #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/organisations/` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | query | string | GET | Search query | N/A | NO | ## Create organisation #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/organisations/` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | name | string | POST | Organisation Name | N/A | YES | ## Update organisation details #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/organisations/{id}` | HTTP/S | PUT | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | id | uint64 | PATH | Organisation ID | N/A | NO | | name | string | POST | Organisation Name | N/A | YES | ## Remove organisation #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/organisations/{id}` | HTTP/S | DELETE | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | id | uint64 | PATH | Organisation ID | N/A | YES | ## Read organisation details #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/organisations/{id}` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | id | uint64 | GET | Organisation ID | N/A | YES | ## Archive organisation #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/organisations/{id}/archive` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | id | uint64 | PATH | Organisation ID | N/A | YES | # Permissions ## Retrieve defined permissions #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/permissions/` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | ## Retrieve role permissions #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/permissions/{roleID}/rules` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | roleID | uint64 | PATH | Role ID | N/A | YES | ## Remove all defined role permissions #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/permissions/{roleID}/rules` | HTTP/S | DELETE | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | roleID | uint64 | PATH | Role ID | N/A | YES | ## Update permission settings #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/permissions/{roleID}/rules` | HTTP/S | PATCH | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | roleID | uint64 | PATH | Role ID | N/A | YES | | permissions | []rules.Rule | POST | List of permissions to set | N/A | YES | # Roles An organisation may have many roles. Roles may have many channels available. Access to channels may be shared between roles. ## List roles #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/roles/` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | query | string | GET | Search query | N/A | NO | ## Update role details #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/roles/` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | name | string | POST | Name of Role | N/A | YES | | members | []string | POST | Role member IDs | N/A | NO | ## Update role details #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/roles/{roleID}` | HTTP/S | PUT | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | roleID | uint64 | PATH | Role ID | N/A | YES | | name | string | POST | Name of Role | N/A | NO | | members | []string | POST | Role member IDs | N/A | NO | ## Read role details and memberships #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/roles/{roleID}` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | roleID | uint64 | PATH | Role ID | N/A | YES | ## Remove role #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/roles/{roleID}` | HTTP/S | DELETE | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | roleID | uint64 | PATH | Role ID | N/A | YES | ## Archive role #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/roles/{roleID}/archive` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | roleID | uint64 | PATH | Role ID | N/A | YES | ## Move role to different organisation #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/roles/{roleID}/move` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | roleID | uint64 | PATH | Role ID | N/A | YES | | organisationID | uint64 | POST | Role ID | N/A | YES | ## Merge one role into another #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/roles/{roleID}/merge` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | roleID | uint64 | PATH | Source Role ID | N/A | YES | | destination | uint64 | POST | Destination Role ID | N/A | YES | ## Returns all role members #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/roles/{roleID}/members` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | roleID | uint64 | PATH | Source Role ID | N/A | YES | ## Add member to a role #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/roles/{roleID}/member/{userID}` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | roleID | uint64 | PATH | Source Role ID | N/A | YES | | userID | uint64 | PATH | User ID | N/A | YES | ## Remove member from a role #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/roles/{roleID}/member/{userID}` | HTTP/S | DELETE | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | roleID | uint64 | PATH | Source Role ID | N/A | YES | | userID | uint64 | PATH | User ID | N/A | YES | # Users ## Search users (Directory) #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/users/` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | query | string | GET | Search query to match against users | N/A | NO | | username | string | GET | Search username to match against users | N/A | NO | | email | string | GET | Search email to match against users | N/A | NO | ## Create user #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/users/` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | email | string | POST | Email | N/A | YES | | name | string | POST | Name | N/A | NO | | handle | string | POST | Handle | N/A | NO | | kind | string | POST | Kind (normal, bot) | N/A | NO | ## Update user details #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/users/{userID}` | HTTP/S | PUT | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | userID | uint64 | PATH | User ID | N/A | YES | | email | string | POST | Email | N/A | YES | | name | string | POST | Name | N/A | YES | | handle | string | POST | Handle | N/A | NO | | kind | string | POST | Kind (normal, bot) | N/A | NO | ## Read user details and memberships #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/users/{userID}` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | userID | uint64 | PATH | User ID | N/A | YES | ## Remove user #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/users/{userID}` | HTTP/S | DELETE | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | userID | uint64 | PATH | User ID | N/A | YES | ## Suspend user #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/users/{userID}/suspend` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | userID | uint64 | PATH | User ID | N/A | YES | ## Unsuspend user #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/users/{userID}/unsuspend` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | userID | uint64 | PATH | User ID | N/A | YES |