Organizations

Table of Contents

• Intro
• The organization object
• Create an organization
• Read data of one organization
• List the sub organizations of an organization

Intro

Organizations are what rokka uses to group images together. A user can be part of multiple organizations. An organization is also part of the url to use the API and the rendering backend. It's a best practice to have one organization per backend that manages images. For example if you run two shops that might have overlapping images, having two separate organizations would be advisable.

The organization object

To see all the organizations below a master organization, use List the sub organizations of an organization.

Create an organization

With a user, you can create new organizations on the /organizations endpoint.

curl -H 'Content-Type: application/json' -X PUT 'https://api.rokka.io/organizations/awesomecompany' -d '{
    "billing_email": "my.email@mail.com",
    "display_name": "My Awesome Company"
}'

$client = \Rokka\Client\Factory::getUserClient();

$client->setCredentials('apiKey');

$organization = $client->createOrganization('awesomecompany', 'my.email@mail.com', 'My Awesome Company');

var_dump($organization);

Note the use of the websafe name as part of the url on where to put the request.

You can also pass an optional master_organization field in the body to create a sub-organization of an existing one. That needs the admin role on it. Without the field, the new organization is put below the master organization of your other organizations, but only if you're admin of that master organization. Otherwise, or with "master_organization": null, it becomes its own master organization.

The return is the full organization object.

At the same time a membership relation is created, making you the admin of the new organization.

Read data of one organization

To retrieve the metadata, a simple GET request will do. Anyone with read rights can do so on this organization.

curl -X GET 'https://api.rokka.io/organizations/awesomecompany'

$client = \Rokka\Client\Factory::getUserClient();

$client->setCredentials('apiKey');

$organization = $client->getOrganization('awesomecompany');

var_dump($organization);

The return is the full organization object.

List the sub organizations of an organization

If you run a master organization with sub-organizations below it — the ones whose usage is aggregated onto the master's invoice — you can list them on the /organizations/{organization}/sub_organizations endpoint. It needs the admin or admin:read role on that organization. Try it out

curl -X GET 'https://api.rokka.io/organizations/awesomecompany/sub_organizations' -H 'Api-Key: myKey'

It returns a total and an items array, one entry per sub-organization, sorted by name:

{
  "organization": "awesomecompany",
  "master_organization": "awesomecompany",
  "total": 2,
  "items": [
    {
      "name": "awesomecompany-shop",
      "id": "251581fc-12ba-466b-bb21-34d23838dc83",
      "display_name": "Awesome Company Shop",
      "billing_email": "my.email@mail.com",
      "created": "2024-03-01T14:00:00+01:00"
    },
    {
      "name": "awesomecompany-www",
      "id": "c8791715-a873-475e-96b2-5ffd488112e7",
      "display_name": "Awesome Company Website",
      "billing_email": "my.email@mail.com",
      "created": "2025-11-12T08:30:00+01:00"
    }
  ]
}

The organization you asked for is not part of items — it is echoed back as organization, so items really only contains the organizations below it. Disabled sub-organizations are left out.

rokka does not support nesting master organizations, so an organization that is itself a sub-organization has no sub-organizations of its own. Asking this on one answers with an empty list, and the master_organization field tells you which organization to ask instead:

{
  "organization": "awesomecompany-shop",
  "master_organization": "awesomecompany",
  "total": 0,
  "items": []
}

It deliberately doesn't expand to that master's other sub-organizations, since you may well have no rights on them.