@@ -3,8 +3,6 @@ id: external-id
3
3
title : External Identifiers
4
4
---
5
5
6
- # Using external identifiers (` external_id ` )
7
-
8
6
This guide explains how to configure and use the ` external_id ` field in Ory Kratos to support external primary identifiers such as
9
7
` customer_id ` , ` employee_id ` , or similar. This is especially useful for migrations from systems where you need to preserve
10
8
identifiers or support user-defined primary identifiers.
@@ -29,18 +27,14 @@ This helps simplify migrations, reduce mapping layers, and align Kratos with you
29
27
30
28
## Configuration
31
29
32
- ### 1. Use ` external_id ` via API, not schema
30
+ ### Use ` external_id ` via API, not schema
33
31
34
32
The ` external_id ` is ** not** part of the identity JSON Schema. Instead, it is a dedicated top-level attribute in API requests that
35
33
create or update identities.
36
34
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.
40
36
41
- :::
42
-
43
- ### 2. Use ` external_id ` in JWT ` sub ` claim
37
+ ### Use ` external_id ` in JWT ` sub ` claim
44
38
45
39
Set the ` subject_source ` to ` external_id ` in the tokenization config:
46
40
@@ -60,12 +54,8 @@ session:
60
54
61
55
This will populate the ` sub` claim in JWTs with the value of `external_id`.
62
56
63
- :::warning
64
-
65
57
If `external_id` is not set for a user when `subject_source` is `external_id`, tokenization will fail.
66
58
67
- :: :
68
-
69
59
# # API usage
70
60
71
61
# ## 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
157
147
}
158
148
` ` `
159
149
160
- :::warning
161
-
162
150
If `external_id` is missing, tokenization will fail.
163
151
164
- :: :
165
-
166
152
# # Migration guide
167
153
168
154
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).
170
156
171
157
# ## Use `PATCH /admin/identities`
172
158
0 commit comments