Core
PaaS v2.x
2

Organizations #

An organization is the top-level Kuzzle PaaS tenant. It groups projects, members and access rights under a single banner.

Controller: organization

Base HTTP route:

/_/organizations

An organization is identified by its tenant index, for example paas-org-my-company.

Create an organization #

const organization = await kuzzle.query({
  controller: 'organization',
  action: 'create',
  name: 'my-company',
  description: 'Acme Inc.'
});

HTTP route:

POST /_/organizations?name=my-company&description=Acme%20Inc.

The authenticated user becomes the organization owner. Organization creation is reserved to platform administrators, unless the platform is configured to allow self-service organization creation.

List my organizations #

Lists the organizations the authenticated user belongs to.

const organizations = await kuzzle.query({
  controller: 'organization',
  action: 'list'
});

HTTP route:

GET /_/organizations

Get an organization #

const organization = await kuzzle.query({
  controller: 'organization',
  action: 'get',
  organizationId: 'paas-org-my-company'
});

HTTP route:

GET /_/organizations/:organizationId

Get organization statistics #

Returns aggregate counters for the organization (projects, environments, members).

const stats = await kuzzle.query({
  controller: 'organization',
  action: 'getStats',
  organizationId: 'paas-org-my-company'
});

HTTP route:

GET /_/organizations/:organizationId/stats

Delete an organization #

await kuzzle.query({
  controller: 'organization',
  action: 'delete',
  organizationId: 'paas-org-my-company'
});

HTTP route:

DELETE /_/organizations/:organizationId

Deleting an organization does not cascade: it removes the organization itself only. It is refused (412 Precondition Failed) while the organization still holds projects or machine identities: delete its machine identities, then its projects, first.

Members and roles #

An organization member has one of four roles:

  • owner: full control, including deleting the organization.
  • admin: manage projects, members and settings.
  • member: access the projects they are attached to, cut releases and deploy them.
  • external: read-only access to the projects they are attached to.

See Authorization for the detail. Adding, updating and removing members requires an owner or admin role.

List members #

Returns members with their roles and project attachments. k8sAccessEligible tells whether the member can receive Kubernetes access to their projects (federated accounts only, see Kubernetes access).

const members = await kuzzle.query({
  controller: 'organization',
  action: 'listMembers',
  organizationId: 'paas-org-my-company'
});

HTTP route:

GET /_/organizations/:organizationId/members

Add an existing user #

Adds a user who already has a Kuzzle account. To onboard someone who has never logged in, use an invitation instead.

await kuzzle.query({
  controller: 'organization',
  action: 'addMember',
  organizationId: 'paas-org-my-company',
  userId: 'kuid-john-doe',
  role: 'member'
});

HTTP route:

POST /_/organizations/:organizationId/members?userId=kuid-john-doe&role=member

Change a member role #

await kuzzle.query({
  controller: 'organization',
  action: 'updateMemberRole',
  organizationId: 'paas-org-my-company',
  userId: 'kuid-john-doe',
  role: 'admin'
});

HTTP route:

PUT /_/organizations/:organizationId/members/:userId?role=admin

Remove a member #

await kuzzle.query({
  controller: 'organization',
  action: 'removeMember',
  organizationId: 'paas-org-my-company',
  userId: 'kuid-john-doe'
});

HTTP route:

DELETE /_/organizations/:organizationId/members/:userId

Removing a member also revokes their Kubernetes access to every project they were attached to.

Invitations #

Invitations onboard members by email, including people who have never logged in. Invitations are resolved automatically at the invited user's first login. A federated email (for example @kuzzle.io) is authenticated through the realm's identity federation; any other domain is onboarded as a local Keycloak account.

Invite a member #

await kuzzle.query({
  controller: 'organization',
  action: 'inviteMember',
  organizationId: 'paas-org-my-company',
  email: 'john.doe@example.com',
  role: 'member',
  body: {
    projectIds: ['my-project'],
    redirectUri: 'https://console.example.com'
  }
});

HTTP route:

POST /_/organizations/:organizationId/invitations?email=john.doe@example.com&role=member

The optional body carries projectIds (projects the invitee is attached to on acceptance) and redirectUri (the console origin used in the local-account setup email).

List pending invitations #

const invitations = await kuzzle.query({
  controller: 'organization',
  action: 'listInvitations',
  organizationId: 'paas-org-my-company'
});

HTTP route:

GET /_/organizations/:organizationId/invitations

Revoke an invitation #

await kuzzle.query({
  controller: 'organization',
  action: 'revokeInvitation',
  organizationId: 'paas-org-my-company',
  email: 'john.doe@example.com'
});

HTTP route:

DELETE /_/organizations/:organizationId/invitations?email=john.doe@example.com

Machine identities #

A machine identity is a credential-less CI/CD principal owned by the organization. It holds registry API keys only and is used to authenticate automated pipelines. See Projects for issuing scoped API keys and Access private packages.

Create a machine identity #

const identity = await kuzzle.query({
  controller: 'organization',
  action: 'createIdentity',
  organizationId: 'paas-org-my-company',
  name: 'ci-deployer',
  description: 'GitHub Actions deployer'
});

HTTP route:

POST /_/organizations/:organizationId/identities?name=ci-deployer

List machine identities #

const identities = await kuzzle.query({
  controller: 'organization',
  action: 'listIdentities',
  organizationId: 'paas-org-my-company'
});

HTTP route:

GET /_/organizations/:organizationId/identities

Update a machine identity #

Only the description can be updated; the identity name and Kuzzle user id are immutable.

await kuzzle.query({
  controller: 'organization',
  action: 'updateIdentity',
  organizationId: 'paas-org-my-company',
  identityId: 'app-my-company-ci-deployer',
  description: 'Updated description'
});

HTTP route:

PUT /_/organizations/:organizationId/identities/:identityId?description=Updated%20description

Delete a machine identity #

Revokes the identity's API keys and removes its Kuzzle user.

await kuzzle.query({
  controller: 'organization',
  action: 'deleteIdentity',
  organizationId: 'paas-org-my-company',
  identityId: 'app-my-company-ci-deployer'
});

HTTP route:

DELETE /_/organizations/:organizationId/identities/:identityId

Activity #

Reads the organization lifecycle activity (project, environment and application create/delete events), most recent first. Available to any member.

const activity = await kuzzle.query({
  controller: 'organization',
  action: 'listActivity',
  organizationId: 'paas-org-my-company'
});

HTTP route:

GET /_/organizations/:organizationId/activity

Import a legacy project #

Migrates a project of the former "one project = one tenant" model (index paas-project-<name>) into an existing organization, as one of its projects. Reserved to platform administrators.

The action is a dry run by default: it returns a report of what the migration would do (moved, skipped, errors) and writes nothing. Only an explicit dryRun: false runs it: the project is created in the organization, its environments (and their applications) are moved to the organization index, and the legacy owners become organization members attached to the project.

const report = await kuzzle.query({
  controller: 'organization',
  action: 'importProject',
  legacyProjectId: 'paas-project-my-project',
  organizationId: 'paas-org-my-company',
  dryRun: false,
  ownerRole: 'owner'
});

HTTP route:

POST /_/organizations/migrations/import-project

Arguments:

  • legacyProjectId: the legacy project tenant index.
  • organizationId: the target organization.
  • dryRun (optional): defaults to a dry run; false (boolean or string) runs the migration.
  • ownerRole (optional): organization role granted to the migrated owners, one of owner, admin, member, external. Defaults to owner.

Project Kubernetes access (platform administrators) #

Reconciles the Kubernetes access of project members with the identity provider and the cluster. Reserved to platform administrators.

checkProjectsK8sAccess is read-only: for every project (or those of organizationId), it reports the expected roles of the federated members, the roles they actually hold, the namespace RoleBindings, and the gaps (issues).

const { projects, duplicateShortNames } = await kuzzle.query({
  controller: 'organization',
  action: 'checkProjectsK8sAccess',
  organizationId: 'paas-org-my-company' // optional
});

alignProjectsK8sAccess fixes the gaps: it poses the RoleBindings, removes outdated ones, stores a level for each federated member (the one they already hold, support otherwise) and grants or revokes their roles. Like importProject, it is a dry run by default; only dryRun: false writes. Roles held by users outside the project are reported, never revoked.

const { projects } = await kuzzle.query({
  controller: 'organization',
  action: 'alignProjectsK8sAccess',
  organizationId: 'paas-org-my-company', // optional
  projectId: 'my-project', // optional, requires organizationId
  dryRun: false
});

HTTP routes:

GET /_/organizations/migrations/project-k8s-access
POST /_/organizations/migrations/project-k8s-access