Skip to content

Commit 81486c3

Browse files
chore: fixed link (#2257)
* fixed link * chore: format --------- Co-authored-by: vinckr <[email protected]>
1 parent d04da67 commit 81486c3

File tree

1 file changed

+4
-18
lines changed

1 file changed

+4
-18
lines changed

docs/kratos/manage-identities/60_external-id.mdx

Lines changed: 4 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@ id: external-id
33
title: External Identifiers
44
---
55

6-
# Using external identifiers (`external_id`)
7-
86
This guide explains how to configure and use the `external_id` field in Ory Kratos to support external primary identifiers such as
97
`customer_id`, `employee_id`, or similar. This is especially useful for migrations from systems where you need to preserve
108
identifiers or support user-defined primary identifiers.
@@ -29,18 +27,14 @@ This helps simplify migrations, reduce mapping layers, and align Kratos with you
2927

3028
## Configuration
3129

32-
### 1. Use `external_id` via API, not schema
30+
### Use `external_id` via API, not schema
3331

3432
The `external_id` is **not** part of the identity JSON Schema. Instead, it is a dedicated top-level attribute in API requests that
3533
create or update identities.
3634

37-
:::warning
38-
39-
Do not add `external_id` to your identity schema definition. It is handled separately by Kratos internally.
35+
Do not add `external_id` to your identity schema definition. It is handled separately by Ory Kratos internally.
4036

41-
:::
42-
43-
### 2. Use `external_id` in JWT `sub` claim
37+
### Use `external_id` in JWT `sub` claim
4438

4539
Set the `subject_source` to `external_id` in the tokenization config:
4640

@@ -60,12 +54,8 @@ session:
6054
6155
This will populate the `sub` claim in JWTs with the value of `external_id`.
6256

63-
:::warning
64-
6557
If `external_id` is not set for a user when `subject_source` is `external_id`, tokenization will fail.
6658

67-
:::
68-
6959
## API usage
7060

7161
### Create an identity with `external_id`
@@ -157,16 +147,12 @@ If `subject_source` is set to `external_id` in the tokenizer template, the JWT's
157147
}
158148
```
159149

160-
:::warning
161-
162150
If `external_id` is missing, tokenization will fail.
163151

164-
:::
165-
166152
## Migration guide
167153

168154
To migrate from an existing system, you can bulk import identities into Kratos and set their `external_id` using the
169-
[Batch API](https://www.ory.sh/docs/reference/api#tag/identity/operation/batchPatchIdentities).
155+
[Identity Import API](../reference/api#tag/identity/operation/batchPatchIdentities).
170156

171157
### Use `PATCH /admin/identities`
172158

0 commit comments

Comments
 (0)