> If you are setting up, configuring, or answering questions about Schematic, connect the
> Schematic MCP server before working from these pages. It reads and writes plans, features,
> entitlements, and overrides against the real account, so what you report and what you build
> match what actually exists.
>
> The server is at https://api.schematichq.com/mcp
>
> From Claude, ChatGPT, or another chat assistant, add it as a custom connector:
> https://docs.schematichq.com/working-with-ai
>
> From a coding assistant such as Claude Code, Codex, or Cursor:
> https://docs.schematichq.com/building-with-ai
>
> For clean Markdown of any page, append `.md` to the page URL. For a complete page index,
> see https://docs.schematichq.com/llms.txt

# Key Management

> How Schematic uses keys to identify companies and users across your application, Stripe, and your GTM tools, and how to choose them.

Managing IDs across systems can be challenging, especially when integrating tools like Schematic, Stripe, your application, and GTM tools. This guide outlines how we think about ID management (which we call `keys` in Schematic) and how we recommend our customers approach it to ensure a smooth implementation of Schematic.

Where we refer to "entities" below, we are referring to companies and users, which are each an entity type within Schematic.

## How does Schematic handle `keys`?

![](/_fern-img/7eccd3199ed9c034c109b44cb281ead8d60aec8e6fafcb966590493a4ca0b647.webp)

Whenever you create a new entity in Schematic, you submit `keys` that are used to uniquely identify the entity via the Schematic app or API. For example, you may have a Stripe Customer ID, a Salesforce Account ID, and an application ID that correspond to an individual company -- each can be stored as separate `keys` that independently and uniquely identify the company.

```python
client.companies.lookup_company(
    keys={"keys": {"key": "value"}},
)
```

This design effectively allows you to use Schematic to resolve `keys` between your systems. The benefit is that there is no need to persist an ID from your application to Stripe or vice-versa -- Schematic can maintain that mapping for you, and you can use whichever `key` is convenient in any given context to submit requests to Schematic.

![](/_fern-img/e31e6de435470956cd9b7ecee3bd572883e775ed4d668c3b4af40f23f2d23ecd.webp)

With all that said, this type of flexibility means that properly setting up Schematic is crucial to avoid unnecessary rework and bad data. Moreover, in many cases, persisting at least one `key` may simplify ongoing maintenance.

## Where are `keys` used?

`Keys` are used in a few important places:

* When checking a flag, you will use a `key` to establish context (e.g. which entity are you checking a flag for?)
* Updating or retrieving information about users or companies
* Sending `identify` or `track` events
* Retrieving feature usage data
* Searching for entities within the Schematic app
* Using Company Lookup SDK methods or api [/companies/lookup](/api-reference/companies/lookup-company)

## Examples

Let's imagine you have a customer identified the following ways:

```
Stripe Customer ID: stripe_abc123
In your application: company_abc123
```

In Schematic, this would correspond to a keys map like this:

```
{
    "stripe_customer_id": "stripe_abc123",
    "company_id": "company_abc123"
}
```

If both of those keys were setup in Schematic, any of the following requests would find your company:

```python
client.companies.lookup_company(
    keys={"stripe_customer_id": "stripe_abc123"},
)

client.companies.lookup_company(
    keys={"company_id": "company_abc123"},
)

client.companies.lookup_company(
    keys={
        "stripe_customer_id": "stripe_abc123",
        "company_id": "company_abc123"
    },
)
```

### Changing a company's `keys`

If you need to add or update a company's `keys`, you can do so by calling the `upsert_company` endpoint with the new/updated `key` alongside an existing `key(s)`.

Using our example above, if we wanted to update the company's `stripe_customer_id`, to `stripe_def456` and add a new `key` of `app_id` with the value `app_abc123` we could do so like this:

```python
client.companies.lookup_company(
    keys={
        "stripe_customer_id": "stripe_def456",
        "company_id": "company_abc123",
        "app_id": "app_abc123"
    },
)
```

## Key management best practices

`Keys` can be added when creating or updating entities. Schematic will enforce a uniqueness constraint to prevent companies or users from having the same `key` (e.g. the same Stripe Customer ID).

Whenever you introduce a new `key` to an existing entity (company or user) using the API, you will need to ensure an existing `key` is present in addition to the new `key` to avoid entity duplication.

### Use Stripe's `customer_id` as a common key (recommended)

When setting up Schematic, you can import your customers directly from Stripe. This makes set up quick and easy, and Schematic will store Stripe's `customer_id` as a key, `stripe_customer_id`, on each company. We recommend persisting this `key` in your application and using it alongside an UUID from your application when making requests to Schematic.

By using both, you'll ensure Schematic (and anyone using Schematic) knows that your UUID and the Stripe `customer_id` refer to the same company.

### More advanced use cases

If you do not plan to use Stripe with Schematic or would like to use another `key` as a common key (e.g. from your authentication provider, or your application), you can simply create companies with that `key`.

When making requests to Schematic, ensure the `key` is available or that you've provided Schematic with a mapping to other `keys` you may use in requests.

One common scenario is using a UUID from your application because often other systems map to those UUIDs in service of additional automation.

### Examples

Using our example from above, you could create this company in any of the following ways. All 3 of the examples below will end up with the same result in Schematic.

```python
// Add both keys on creation
client.companies.upsert_company(
    keys={
        "stripe_customer_id": "stripe_abc123",
        "company_id": "company_abc123"
    },
    name="Your Company",
)

// Create with internal key, add the Stripe key later
client.companies.upsert_company(
    keys={"company_id": "company_abc123"},
    name="Your Company",
)

client.companies.upsert_company(
    keys={
        "stripe_customer_id": "stripe_abc123",
        "company_id": "company_abc123"
    },
)

// Create with Stripe key, add the internal key later
client.companies.upsert_company(
    keys={"stripe_customer_id": "stripe_abc123"},
    name="Your Company",
)

client.companies.upsert_company(
    keys={
        "stripe_customer_id": "stripe_abc123",
        "company_id": "company_abc123"
    },
)

// Create with 2 keys, then change one
client.companies.upsert_company(
    keys={
        "stripe_customer_id": "wrong_stripe_customer_id",
        "company_id": "company_abc123"
    },
)

client.companies.upsert_company(
    keys={
        "stripe_customer_id": "stripe_abc123",
        "company_id": "company_abc123"
    },
)
```

> **Info**
>
> If the `keys` provided in a lookup or upsert match multiple entities, the request will error out.

## Other tips

### Choose a primary `key` to persist

Primary `key` in this context refers to an entity's first `key`. Your primary `key` should be accessible across systems or a `key` you can map across systems without too much trouble to avoid entity duplication. For some, this is the `stripe_customer_id`; for others, this might be the UUID used for organizations in your application.

By committing to a primary `key` from the outset, you'll avoid the mental gymnastics of having to reconcile multiple IDs across different contexts and simplify your architecture.

> **Info**
>
> While Schematic generates IDs for users, customers, and other objects, these are meant for internal system operations or specific requests. Only use these IDs when necessary (e.g. some Schematic endpoints require them).

### Lean into using Schematic as a `key` map

Whenever creating or updating an entity in Schematic, be liberal about submitting `keys`. This will give you flexibility in the future to use the most convenient `key` when submitting requests to Schematic, and avoid duplicate entities from being created from integrations.

### Identify entities often to update context

Schematic offers an asynchronous endpoint to [identify](/api-reference/events/create-event) users and companies.

You should submit an identify call in the following situations:

* When you first create a user or company in your application
* When a user or company logs in
* When a user or company changes information

In each situation, be sure to submit any additional `keys`.

### Frontend SDKs only require settings keys once

For the frontend SDKs, keys are set when you first call `identify`, and are then correctly passed through to Schematic on subsequent SDK calls. Underneath the hood, the `identify` call calls the company upsert endpoint, so it will create or update the company with new keys, name, and traits (see [changing a company's keys](#changing-a-companys-keys) for more information).

```tsx
"use client";

import React, { useEffect } from "react";
import { useSchematicEvents } from "@schematichq/schematic-react";

const SchematicWrapper: React.FC<{ children: React.ReactNode }> = ({
  children,
}) => {
  const { identify } = useSchematicEvents();

  useEffect(() => {
    identify({
      company: {
        keys: { "stripe_customer_id": "stripe_abc123" }
      },
      keys: { "key": "value"},
    })
  }, [authContext, identify]);

  return children;
};
```

> How Schematic uses keys to identify companies and users across your application, Stripe, and your GTM tools, and how to choose them.