> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation. > > - **Claude Code**: `/plugin marketplace add scalekit-inc/claude-code-authstack` then `/plugin install @scalekit-auth-stack` > - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install @scalekit-auth-stack` > - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `` > - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill ` > > `` / ``: `agentkit`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # 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: ```bash title="Create a new organization with an external ID" curl https:///api/v1/organizations \ --request POST \ --header 'Content-Type: application/json' \ --data '{ "display_name": "Megasoft Inc", "external_id": "CUST-12345-MGSFT", }' ``` #### Update an existing organization's external ID To change an organization's external ID, use the update endpoint: ```bash title="Update an existing organization's external ID" curl 'https:///api/v1/organizations/{id}' \ --request PATCH \ --header 'Content-Type: application/json' \ --data '{ "display_name": "Megasoft Inc", "external_id": "TENANT-12345-MGSFT", }' ``` ### 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: ```bash title="Create a new organization with metadata" curl https:///api/v1/organizations \ --request POST \ --header 'Content-Type: application/json' \ --data '{ "display_name": "Megasoft Inc", "metadata": { "invoice_email": "invoices@megasoft.com" } }' ``` #### Update an existing organization's metadata To modify an organization's metadata, use the update endpoint: ```bash title="Update an existing organization's metadata" curl 'https:///api/v1/organizations/{id}' \ --request PATCH \ --header 'Content-Type: application/json' \ --data '{ "display_name": "Megasoft Inc", "metadata": { "invoice_email": "billing@megasoft.com" } }' ``` ### 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: ```text us-east-CUST-12345 # US East account 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. > tip: Disable SCIM before deleting > > Before deleting an organization, ask your customer to disable SCIM provisioning in their identity provider. This prevents error logs on their side after the organization is removed. --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |