Metadata and External IDs

Store additional information about users and organizations.

Introduction

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

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.

Metadata

You can add up to 10 key-value pairs to an organization or user within these data limits:

Key: Up to 40 characters long. ASCII only.

Value: Up to 500 characters long. ASCII only.

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.

Set an external identifier

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.

Query by external identifier

To query an organization or user by their external identifier, use the Get organization by external identifier or Get user by external identifier endpoints.

Add and update metadata

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:

Create an organization

Update an organization

Create a user

Update a user

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": {}
}

JWT TemplatesCustomize the claims in your application's access tokens

Up next