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. Depending on the platform configuration, organization creation may be reserved to platform administrators.

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

Members and roles #

An organization member has one of three roles:

owner: full control, including deleting the organization.
admin: manage projects, members and settings.
member: access granted projects.

Adding, updating and removing members requires an owner or admin role.

List members #

Returns members with their roles and project attachments.

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

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