Public API #

The Kuzzle PaaS backend exposes Kuzzle controllers to manage organizations, projects, environments and applications.

You can call the API with any Kuzzle SDK:

await kuzzle.query({
  controller: 'org-environment',
  action: 'list',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project'
});

The same actions are also exposed as HTTP routes. The route paths documented in this section are relative to your Kuzzle PaaS API endpoint.

Authentication #

Most actions require an authenticated Kuzzle user. Send the JWT returned by the authentication flow with your SDK or as a bearer token when using HTTP.

See Authentication.

Main resources #

Resource hierarchy #

Organization
+-- Project
    +-- Environment
        +-- Application

An organization is the top-level tenant. A project belongs to one organization. An environment belongs to one project. An application belongs to one environment.

Common conventions #

organizationId is the organization tenant index, for example paas-org-my-company.
projectId is the project (soft tenant) identifier inside the organization, for example my-project.
environmentId is the environment name, for example staging or production.
applicationId is the application _id, for example api or webapp.
Most scalar parameters (names, ids, flags) are passed as query parameters over HTTP and as top-level query arguments with the SDK. Structured payloads (an application definition, an image to deploy) are passed in the request body.
Long-running operations may return an acknowledgement (for example "creating" or "deleted") before the platform has finished provisioning or deleting external resources.
The API returns plain domain objects for organization, project, environment and application resources.

Public controller summary #

Controller	Purpose
`organization`	Manage organizations, their members and roles, invitations, machine identities, and the projects they own.
`org-environment`	Create, update, refresh, enable, disable and delete environments, and manage their monitoring, alerts and Keycloak realm.
`org-application`	Create, update, deploy, enable, disable and delete applications, and read their deployable image versions and runtime status.
`org-apikey`	Issue and revoke scoped API keys for a project's registry access.
`registry`	Resolve a caller's registry access from an API key (used by the private package registry).
`sso`	Generate a Keycloak logout URL.

Transitional: the legacy-deploy controller re-serves the deploy and read routes expected by paas-action@<=1.2.2 during the migration to the organizations model. It will be removed in a future release; new integrations should use the org-application controller.