corteza/api/system/spec.json

[
  {
    "title": "Authentication",
    "path": "/auth",
    "entrypoint": "auth",
    "authentication": [],
    "apis": [
      {
        "name": "check",
        "method": "GET",
        "title": "Check JWT token",
        "path": "/check",
        "parameters": {}
      },
      {
        "name": "login",
        "method": "POST",
        "title": "Login user",
        "path": "/login",
        "parameters": {
          "post": [
            {
              "name": "username",
              "type": "string",
              "required": true,
              "title": "Username"
            },
            {
              "name": "password",
              "type": "string",
              "required": true,
              "title": "Password"
            }
          ]
        }
      },
      {
        "name": "logout",
        "method": "GET",
        "title": "Delete JWT token (Sign Out)",
        "path": "/logout",
        "parameters": {}
      }
    ]
  },
  {
    "title": "Organisations",
    "description": "Organisations represent a top-level grouping entity. There may be many organisations defined in a single deployment.",
    "path": "/organisations",
    "entrypoint": "organisation",
    "authentication": [
      "Client ID",
      "Session ID"
    ],
    "apis": [
      {
        "name": "list",
        "method": "GET",
        "title": "List organisations",
        "path": "/",
        "parameters": {
          "get": [
            {
              "type": "string",
              "name": "query",
              "required": false,
              "title": "Search query"
            }
          ]
        }
      },
      {
        "name": "create",
        "method": "POST",
        "title": "Create organisation",
        "path": "/",
        "parameters": {
          "post": [
            {
              "type": "string",
              "name": "name",
              "required": true,
              "title": "Organisation Name"
            }
          ]
        }
      },
      {
        "name": "update",
        "method": "PUT",
        "title": "Update organisation details",
        "path": "/{id}",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "id",
              "required": false,
              "title": "Organisation ID"
            }
          ],
          "post": [
            {
              "type": "string",
              "name": "name",
              "required": true,
              "title": "Organisation Name"
            }
          ]
        }
      },
      {
        "name": "remove",
        "method": "DELETE",
        "title": "Remove organisation",
        "path": "/{id}",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "id",
              "required": true,
              "title": "Organisation ID"
            }
          ]
        }
      },
      {
        "name": "read",
        "method": "GET",
        "title": "Read organisation details",
        "path": "/{id}",
        "parameters": {
          "get": [
            {
              "type": "uint64",
              "name": "id",
              "required": true,
              "title": "Organisation ID"
            }
          ]
        }
      },
      {
        "name": "archive",
        "method": "POST",
        "title": "Archive organisation",
        "path": "/{id}/archive",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "id",
              "required": true,
              "title": "Organisation ID"
            }
          ]
        }
      }
    ]
  },
  {
    "title": "Roles",
    "description": "An organisation may have many roles. Roles may have many channels available. Access to channels may be shared between roles.",
    "path": "/roles",
    "entrypoint": "role",
    "authentication": [
      "Client ID",
      "Session ID"
    ],
    "apis": [
      {
        "name": "list",
        "method": "GET",
        "title": "List roles",
        "path": "/",
        "parameters": {
          "get": [
            {
              "type": "string",
              "name": "query",
              "required": false,
              "title": "Search query"
            }
          ]
        }
      },
      {
        "name": "create",
        "method": "POST",
        "title": "Update role details",
        "path": "/",
        "parameters": {
          "post": [
            {
              "type": "string",
              "name": "name",
              "required": true,
              "title": "Name of Role"
            },
            {
              "type": "[]uint64",
              "name": "members",
              "required": false,
              "title": "Role member IDs"
            }
          ]
        }
      },
      {
        "name": "update",
        "method": "PUT",
        "title": "Update role details",
        "path": "/{roleID}",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "roleID",
              "required": true,
              "title": "Role ID"
            }
          ],
          "post": [
            {
              "type": "string",
              "name": "name",
              "required": false,
              "title": "Name of Role"
            },
            {
              "type": "[]uint64",
              "name": "members",
              "required": false,
              "title": "Role member IDs"
            }
          ]
        }
      },
      {
        "name": "read",
        "method": "GET",
        "title": "Read role details and memberships",
        "path": "/{roleID}",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "roleID",
              "required": true,
              "title": "Role ID"
            }
          ]
        }
      },
      {
        "name": "remove",
        "method": "DELETE",
        "title": "Remove role",
        "path": "/{roleID}",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "roleID",
              "required": true,
              "title": "Role ID"
            }
          ]
        }
      },
      {
        "name": "archive",
        "method": "POST",
        "title": "Archive role",
        "path": "/{roleID}/archive",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "roleID",
              "required": true,
              "title": "Role ID"
            }
          ]
        }
      },
      {
        "name": "move",
        "method": "POST",
        "title": "Move role to different organisation",
        "path": "/{roleID}/move",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "roleID",
              "required": true,
              "title": "Role ID"
            }
          ],
          "post": [
            {
              "type": "uint64",
              "name": "organisationID",
              "required": true,
              "title": "Role ID"
            }
          ]
        }
      },
      {
        "name": "merge",
        "method": "POST",
        "title": "Merge one role into another",
        "path": "/{roleID}/merge",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "roleID",
              "required": true,
              "title": "Source Role ID"
            }
          ],
          "post": [
            {
              "type": "uint64",
              "name": "destination",
              "required": true,
              "title": "Destination Role ID"
            }
          ]
        }
      },
      {
        "name": "memberAdd",
        "method": "POST",
        "title": "Add member to a role",
        "path": "/{roleID}/memberAdd",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "roleID",
              "required": true,
              "title": "Source Role ID"
            }
          ],
          "post": [
            {
              "type": "uint64",
              "name": "userID",
              "required": true,
              "title": "User ID"
            }
          ]
        }
      },
      {
        "name": "memberRemove",
        "method": "POST",
        "title": "Remove member from a role",
        "path": "/{roleID}/memberRemove",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "roleID",
              "required": true,
              "title": "Source Role ID"
            }
          ],
          "post": [
            {
              "type": "uint64",
              "name": "userID",
              "required": true,
              "title": "User ID"
            }
          ]
        }
      }
    ]
  },
  {
    "title": "Users",
    "path": "/users",
    "entrypoint": "user",
    "authentication": [
      "Client ID",
      "Session ID"
    ],
    "apis": [
      {
        "name": "list",
        "method": "GET",
        "title": "Search users (Directory)",
        "path": "/",
        "parameters": {
          "get": [
            {
              "type": "string",
              "name": "query",
              "required": false,
              "title": "Search query to match against users"
            },
            {
              "type": "string",
              "name": "username",
              "required": false,
              "title": "Search username to match against users"
            },
            {
              "type": "string",
              "name": "email",
              "required": false,
              "title": "Search email to match against users"
            }
          ]
        }
      },
      {
        "name": "create",
        "method": "POST",
        "title": "Create user",
        "path": "/",
        "parameters": {
          "post": [
            {
              "name": "email",
              "type": "string",
              "required": true,
              "title": "Email"
            },
            {
              "name": "name",
              "type": "string",
              "required": false,
              "title": "Name"
            },
            {
              "name": "handle",
              "type": "string",
              "required": false,
              "title": "Handle"
            },
            {
              "name": "kind",
              "type": "string",
              "required": false,
              "title": "Kind (normal, bot)"
            }
          ]
        }
      },
      {
        "name": "update",
        "method": "PUT",
        "title": "Update user details",
        "path": "/{userID}",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "userID",
              "required": true,
              "title": "User ID"
            }
          ],
          "post": [
            {
              "name": "email",
              "type": "string",
              "required": true,
              "title": "Email"
            },
            {
              "name": "name",
              "type": "string",
              "required": true,
              "title": "Name"
            },
            {
              "name": "handle",
              "type": "string",
              "required": false,
              "title": "Handle"
            },
            {
              "name": "kind",
              "type": "string",
              "required": false,
              "title": "Kind (normal, bot)"
            }
          ]
        }
      },
      {
        "name": "read",
        "method": "GET",
        "title": "Read user details and memberships",
        "path": "/{userID}",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "userID",
              "required": true,
              "title": "User ID"
            }
          ]
        }
      },
      {
        "name": "remove",
        "method": "DELETE",
        "title": "Remove user",
        "path": "/{userID}",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "userID",
              "required": true,
              "title": "User ID"
            }
          ]
        }
      },
      {
        "name": "suspend",
        "method": "POST",
        "title": "Suspend user",
        "path": "/{userID}/suspend",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "userID",
              "required": true,
              "title": "User ID"
            }
          ]
        }
      },
      {
        "name": "unsuspend",
        "method": "POST",
        "title": "Unsuspend user",
        "path": "/{userID}/unsuspend",
        "parameters": {
          "path": [
            {
              "type": "uint64",
              "name": "userID",
              "required": true,
              "title": "User ID"
            }
          ]
        }
      }
    ]
  },
  {
    "title": "Permissions",
    "parameters": {},
    "entrypoint": "permission",
    "path": "/permissions",
    "authentication": [
      "Client ID",
      "Session ID"
    ],
    "struct": [
      {
        "imports": [
          "github.com/crusttech/crust/internal/rules"
        ]
      }
    ],
    "apis": [
      {
        "name": "read",
        "path": "/{roleID}/rules",
        "method": "GET",
        "title": "Retrieve role permissions",
        "parameters": {
          "path": [
            {
              "name": "roleID",
              "type": "uint64",
              "required": true,
              "title": "Role ID"
            }
          ]
        }
      },
      {
        "name": "delete",
        "path": "/{roleID}/rules",
        "method": "DELETE",
        "title": "Remove all defined role permissions",
        "parameters": {
          "path": [
            {
              "name": "roleID",
              "type": "uint64",
              "required": true,
              "title": "Role ID"
            }
          ]
        }
      },
      {
        "name": "update",
        "path": "/{roleID}/rules",
        "method": "PATCH",
        "title": "Update permission settings",
        "parameters": {
          "path": [
            {
              "name": "roleID",
              "type": "uint64",
              "required": true,
              "title": "Role ID"
            }
          ],
          "post": [
            {
              "name": "permissions",
              "type": "[]rules.Rule",
              "required": true,
              "title": "List of permissions to set"
            }
          ]
        }
      }
    ]
  }
]