Managing organization identifiers & metadata

Learn how to use external IDs and metadata to manage and track organizations in Scalekit, associating your own identifiers and storing custom key-value pairs.

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.

External ID constraints

External IDs have the following constraints:

Unique per environment: Each external ID must be unique across all organizations in the same Scalekit environment, regardless of region.
Maximum length: 255 characters.
Searchable by external_id: You can look up organizations by external_id using the list organizations endpoint. You cannot search organizations by a metadata field.

Multi-region external ID pattern

If your application operates across multiple regions and your internal account IDs are unique only within a region, prefix each external ID with the region name to ensure uniqueness across your Scalekit environment:

1
us-east-CUST-12345   # US East account
2
eu-west-CUST-12345   # EU West account with the same internal ID

This pattern keeps the region and account identifier in a single field and stays within the 255-character limit.

Organization deletion and SCIM

When you delete an organization in Scalekit, Scalekit automatically deletes all associated connections and SCIM configurations. No charges apply after deletion.

However, if your customer’s identity provider has SCIM provisioning enabled, the IdP will continue attempting to send SCIM events after the organization is deleted. Because there is no active SCIM endpoint to receive those events, the IdP will log errors for each attempt.