Store additional information about users and organizations.
Metadata is an attribute of organizations and users that allows you to store additional information about these objects, structured as key-value pairs. For example, you can use metadata to store information about a user’s profile picture, or the organization’s address.
External identifiers allow you to associate organizations and users with an identifier in your own system.
External identifiers are an attribute of organizations and users that allows you to associate these objects with an identifier in your own system. Once you have set an external identifier for an object, you can query on it via dedicated endpoints in the WorkOS API.
External identifiers must be unique within your environment and are limited to 64 characters.
You can add up to 10 key-value pairs to an organization or user within these data limits:
If your integration requires more than 10 key-value pairs, consider storing the additional data in your own external database and use an external identifier to associate the data with an organization or user.
Never store sensitive information in metadata such as passwords, API keys, or other private information.
Metadata is returned in the response body for backend API operations that return organization or user objects, but not in the response body of the User Authentication operations. If you want to publicly expose metadata properties from users or organizations in your access tokens, you can use JWT templates to customize claims in your application’s access tokens.
To set an external identifier for an organization or user, include the external_id property in the request body of the Create an organization or Create a user endpoints.
curl --request POST \ --url https://api.workos.com/organizations \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "name": "Foo Corp", "external_id": "2fe01467-f7ea-4dd2-8b79-c2b4f56d0191", } BODY
{ "id": "org_01EHZNVPK3SFK441A1RGBFSHRT", "object": "organization", "name": "Foo Corp", "allow_profiles_outside_organization": false, "external_id": "2fe01467-f7ea-4dd2-8b79-c2b4f56d0191", "metadata": {}, "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "domains": [] }
To update an external identifier, include the external_id property in the request body of the Update an organization or Update a user endpoints.
To query an organization or user by their external identifier, use the Get organization by external identifier or Get user by external identifier endpoints.
Updates to metadata are partial. This means that you only need to include the metadata attributes that you want to update.
Metadata can be included in the request body of the following endpoints:
To add a metadata attribute to an entity, include the key and value pair in the metadata object of the request body.
{ "metadata": { "key": "value" } }
To update a metadata attribute, include the key and value pair in the metadata object of the request body.
{ "metadata": { "key": "new_value" } }
To delete a metadata attribute, set the key to null in the metadata object of the request body.
{ "metadata": { "key": null } }
To delete all metadata attributes, set the metadata property an empty object.
{ "metadata": {} }
Custom metadata and external identifiers can be exposed as claims in JWTs using JWT Templates.
{ "urn:myapp:user_external_id" : {{ user.external_id }}, "urn:myapp:manager_id": {{ user.metadata.manager_id }} }
{ "user": { "external_id": "a4f3d9c7-8b5e-12f0-c6a7-9b1d34e8ac25", "metadata": { "manager_id": "a2f3e220-0cd2-47f1-b2ea-fb3e8c7f4506" } } }
{ "urn:myapp:user_external_id" : "a4f3d9c7-8b5e-12f0-c6a7-9b1d34e8ac25", "urn:myapp:manager_id": "a2f3e220-0cd2-47f1-b2ea-fb3e8c7f4506" }