Managing organization identifiers & metadata

Applications often need to manage and track resources in their own systems. Scalekit provides two features to help with this:

External IDs: Associate your own identifiers with organizations
Metadata: Store custom key-value pairs with organizations

When to use external IDs and metadata

Use these features when you need to:

Track organizations using your own identifiers instead of Scalekit’s IDs
Store additional information about organizations like billing details or internal codes
Integrate Scalekit organizations with your existing systems

Add an external ID to an organization

External IDs let you identify organizations using your own identifiers. You can set an external ID when creating or updating an organization.

Create a new organization with an external ID

This example shows how to create an organization with your custom identifier:

1
curl https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations \
2
  --request POST \
3
  --header 'Content-Type: application/json' \
4
  --data '{
5
  "display_name": "Megasoft Inc",
6
  "external_id": "CUST-12345-MGSFT",
7
}'

Update an existing organization’s external ID

To change an organization’s external ID, use the update endpoint:

1
curl 'https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/{id}' \
2
  --request PATCH \
3
  --header 'Content-Type: application/json' \
4
  --data '{
5
  "display_name": "Megasoft Inc",
6
  "external_id": "TENANT-12345-MGSFT",
7
}'

Add metadata to an organization

Metadata lets you store custom information as key-value pairs. You can add metadata when creating or updating an organization.

Create a new organization with metadata

This example shows how to store billing information with a new organization:

1
curl https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations \
2
  --request POST \
3
  --header 'Content-Type: application/json' \
4
  --data '{
5
  "display_name": "Megasoft Inc",
6
  "metadata": {
7
    "invoice_email": "invoices@megasoft.com"
8
  }
9
}'

Update an existing organization’s metadata

To modify an organization’s metadata, use the update endpoint:

1
curl 'https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/{id}' \
2
  --request PATCH \
3
  --header 'Content-Type: application/json' \
4
  --data '{
5
  "display_name": "Megasoft Inc",
6
  "metadata": {
7
    "invoice_email": "billing@megasoft.com"
8
  }
9
}'

View external IDs and metadata

All organization endpoints that return organization details will include the external ID and metadata in their responses. This makes it easy to access your custom data when working with organizations.