Skip to content

Commit 0abd884

Browse files
andreyudentsovottofellerandreyudentsovottofeller
committed
Move a techincal details under the Technical reference link
1 parent 16ca2ae commit 0abd884

4 files changed

Lines changed: 150 additions & 126 deletions

File tree

‎docs.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,13 @@
109109
"GET /is-valid-root",
110110
"GET /status/{id}"
111111
]
112+
},
113+
{
114+
"group": "Issuers",
115+
"pages": [
116+
"world-id/reference/poh-issuer",
117+
"world-id/reference/nfc-issuer"
118+
]
112119
}
113120
]
114121
},

‎snippets/credential-hero.jsx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
import React from "react";
2-
31
/**
42
* Hero card for credential issuer documentation pages.
53
* Mintlify-safe: no hooks, no client-side state.

‎world-id/credentials/9303.mdx‎

Lines changed: 7 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: "NFC Credential"
33
icon: "passport"
44
iconType: "duotone"
5-
description: "Unique government-issued document (eID) or passports."
5+
description: "A unique government-issued document, such as a passport or eID."
66
"og:image": "https://docs.world.org/images/docs/docs-meta.png"
77
"twitter:image": "https://docs.world.org/images/docs/docs-meta.png"
88
---
@@ -13,7 +13,7 @@ import { CredentialHero } from "/snippets/credential-hero.jsx";
1313

1414
<CredentialHero
1515
title="NFC Credential"
16-
description="Unique government-issued document (eID) or passports."
16+
description="A unique government-issued document, such as a passport or eID."
1717
image="/images/docs/id/issuers/9303/thumbnail.png"
1818
bgColor="#4a1520"
1919
issuerName="Tools for Humanity"
@@ -29,11 +29,11 @@ import { CredentialHero } from "/snippets/credential-hero.jsx";
2929

3030
## Introduction
3131

32-
The NFC Credential represents a uniquely issued government document. It supports passports and eIDs. The availability generally varies by country and continues to be extended over time. An NFC Credential is **guaranteed to be issued to a single World ID per unique document**. In addition to ICAO-9303 compliant documents (such as passports or eIDs), the Japanese [My Number Card](https://en.wikipedia.org/wiki/My_Number_Card) is also supported. This MNC card has different handling internally for enrollment, but the same credential is issued.
32+
The NFC Credential represents a unique government-issued document. It supports passports and eIDs. Availability varies by country and continues to expand over time. An NFC Credential is **guaranteed to be issued to a single World ID per unique document**. In addition to ICAO-9303 compliant documents (such as passports or eIDs), the Japanese [My Number Card](https://en.wikipedia.org/wiki/My_Number_Card) (MNC) is also supported. The MNC flow uses different enrollment handling internally, but it issues the same credential.
3333

3434
## Use Cases
3535

36-
Use the NFC Credential when you need proof of a unique document. This is useful for example for situations where you want to have some sybil resistance but you don't need a strong guarantee of a unique human.
36+
Use the NFC Credential when you need proof of a unique government document. This is useful for applications that need document-level Sybil resistance without requiring a proof of a unique human.
3737

3838
## Credential Structure
3939

@@ -43,7 +43,7 @@ This credential implements the following attributes beyond the defaults in the [
4343
| ---------------------------- | ------------------------------------------------------------------------------------- |
4444
| `genesis_issued_at` | The timestamp of when the unique document was first verified. |
4545
| `expires_at` | The expiration of the document with a maximum of 10 years. |
46-
| `associated_data_commitment` | A commitment to the user's Associated Data (see [Associated Data](#associated-data)). |
46+
| `associated_data_commitment` | A commitment to the user's Associated Data (see [NFC Issuer implementation notes](/world-id/reference/nfc-issuer#associated-data)). |
4747

4848
In addition, the credential implements the following claims:
4949

@@ -66,123 +66,6 @@ Contains a hash of the document's signature from the issuing authority. For pass
6666

6767
Renewal is not supported for this credential. A document can only be enrolled once. From a user standpoint, they will generally obtain a new document from their issuing authority (e.g. a new passport) and register it as a new credential.
6868

69-
## API Reference
69+
## Technical Reference
7070

71-
The API Reference here is only relevant for Authenticators and internal development of the credential.
72-
73-
### Enrollment <Badge disabled icon="lock" color="blue">Coming soon</Badge>
74-
75-
Details coming soon.
76-
77-
### Re-issuance <Badge disabled icon="lock" color="blue">Coming soon</Badge>
78-
79-
Details coming soon.
80-
81-
### Migration
82-
83-
<Info>
84-
This endpoint is intended for World ID v3 holders to obtain v4 NFC
85-
credentials. It is not a general re-issuance endpoint for v4 holders.
86-
</Info>
87-
88-
<ParamField path="method" type="POST">
89-
/v2/migrate
90-
</ParamField>
91-
92-
**Content-Type:** `application/json`
93-
94-
#### Headers
95-
96-
| Header | Type | Required | Description |
97-
| --------------------------- | -------- | -------- | --------------------------------------------------------------------- |
98-
| `x-zkp-proof` | `string` | yes | Base64-encoded JSON containing the ZKP proof and identity commitment. |
99-
| `attestation-gateway-token` | `string` | yes | Attestation gateway token for device integrity verification. |
100-
101-
#### Body fields (common)
102-
103-
| Field | Type | Required | Description |
104-
| -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
105-
| `identityCommitment` | `string` | yes | The holder's identity commitment (decimal or hex with `0x` prefix). Must match the ZKP header. |
106-
| `sub` | `string` | yes | World ID 4.0 blinded subject identifier (hex with `0x` prefix, 256-bit). Must match previous migrations for this identity. |
107-
| `credential` | `object` | yes | Flow-specific credential data (see below). The client decrypts PCP data locally before submission. |
108-
109-
#### Credential fields
110-
111-
<Tabs>
112-
<Tab title="Passport / eID">
113-
The `credential` object contains data extracted and decrypted from the user's Personal Custody Package (PCP) by the client.
114-
115-
| Field | Type | Description |
116-
| ---------------------------------- | -------- | --------------------------------------------------------------------------------------- |
117-
| `credential.sod` | `string` | Base64-encoded SOD (Security Object Document) in DER format from the identity document. |
118-
| `credential.verification_metadata` | `string` | Base64-encoded verification metadata from the original document check. |
119-
120-
```json
121-
{
122-
"identityCommitment": "0x000000000000000000000000000000000000000000000000000000000000000c",
123-
"sub": "0x000000000000000000000000000000000000000000000000000000000000002a",
124-
"credential": {
125-
"sod": "<base64-sod-der>",
126-
"verification_metadata": "<base64-json>"
127-
}
128-
}
129-
```
130-
131-
</Tab>
132-
<Tab title="MNC (My Number Card)">
133-
| Field | Type | Description |
134-
| ------------------- | -------- | ----------------------------------------------------------------- |
135-
| `credential.sd_jwt` | `string` | SD-JWT (Selective Disclosure JWT) from the MNC verification flow. |
136-
137-
```json
138-
{
139-
"identityCommitment": "0x000000000000000000000000000000000000000000000000000000000000000c",
140-
"sub": "0x000000000000000000000000000000000000000000000000000000000000002a",
141-
"credential": {
142-
"sd_jwt": "<sd-jwt-string>"
143-
}
144-
}
145-
```
146-
147-
</Tab>
148-
</Tabs>
149-
150-
#### Success response
151-
152-
```json
153-
{
154-
"result": {
155-
"credential": "<base64-encoded World ID v4 credential>"
156-
}
157-
}
158-
```
159-
160-
#### Error responses
161-
162-
| Status | Error | Description |
163-
| ------ | ------------------ | --------------------------------------------------------------------------- |
164-
| 400 | `invalid_data` | Request payload is malformed or missing required fields. |
165-
| 400 | `sub_mismatch` | `sub` does not match the one used in previous migrations for this identity. |
166-
| 400 | `document_expired` | The identity document has expired and cannot be used for migration. |
167-
| 401 | `unauthorized` | Authentication failed. |
168-
| 404 | `not_found` | No matching enrollment record found for this credential. |
169-
170-
# Internal Documentation
171-
172-
<Note>
173-
This is advanced documentation about the internal workings of the NFC
174-
Credential and is not relevant for RP integration.
175-
</Note>
176-
177-
## Associated Data
178-
179-
The associated data of this credential contains different data groups found in the original document. More information coming soon.
180-
181-
{/* TODO: Add details on the PCP */}
182-
183-
### Associated Data Commitment
184-
185-
To ensure the associated data has guaranteed integrity and can be re-used in the future for credential re-issuance, the commitment is computed as follows:
186-
187-
1. For ICAO-9303 documents, the message digest of the `EF.SOD` signature is used. The message digest is obtained from `SignedData.SignerInfos[0].SignedAttrs` where the signed attribute for the digest is identified by the Object Identifier `1.2.840.113549.1.9.4`. This digest is then hashed with the `blake3` hashing function from the raw bytes. Finally, the `blake3` hash is converted to a field element with modulo reduction.
188-
2. Information on MNC documents coming soon.
71+
For issuer endpoints, migration payloads, and implementation-specific details, see the [NFC Issuer reference](/world-id/reference/nfc-issuer).

‎world-id/reference/nfc-issuer.mdx‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: "NFC Issuer"
3+
description: "NFC issuer endpoints, including migration for World ID v3 NFC credentials."
4+
"og:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png"
5+
"twitter:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png"
6+
---
7+
8+
The NFC issuer exposes endpoints for issuing and migrating NFC credentials. For product-level credential semantics, Sybil-resistance guarantees, and validity details, see [NFC Credential](/world-id/credentials/9303).
9+
10+
<Note>
11+
The base URL is environment-specific. Contact your World ID point of contact for
12+
environment endpoints and access.
13+
</Note>
14+
15+
## Migration
16+
17+
<Warning>
18+
This endpoint is intended for World ID v3 holders to obtain v4 NFC
19+
credentials. It is not a general re-issuance endpoint for v4 holders.
20+
</Warning>
21+
22+
<ParamField path="method" type="POST">
23+
/v2/migrate
24+
</ParamField>
25+
26+
**Content-Type:** `application/json`
27+
28+
### Request
29+
30+
#### Headers
31+
32+
| Header | Type | Required | Description |
33+
| --------------------------- | -------- | -------- | --------------------------------------------------------------------- |
34+
| `x-zkp-proof` | `string` | yes | Base64-encoded JSON containing the ZKP proof and identity commitment. |
35+
| `attestation-gateway-token` | `string` | yes | Attestation gateway token for device integrity verification. |
36+
37+
#### Body fields
38+
39+
| Field | Type | Required | Description |
40+
| -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
41+
| `identityCommitment` | `string` | yes | The holder's identity commitment (decimal or hex with `0x` prefix). Must match the ZKP header. |
42+
| `sub` | `string` | yes | World ID 4.0 blinded subject identifier (hex with `0x` prefix, 256-bit). Must match previous migrations for this identity. |
43+
| `credential` | `object` | yes | Flow-specific credential data (see below). The client decrypts PCP data locally before submission. |
44+
45+
#### Credential fields
46+
47+
<Tabs>
48+
<Tab title="Passport / eID">
49+
The `credential` object contains data extracted and decrypted from the user's Personal Custody Package (PCP) by the client.
50+
51+
| Field | Type | Description |
52+
| ---------------------------------- | -------- | --------------------------------------------------------------------------------------- |
53+
| `credential.sod` | `string` | Base64-encoded SOD (Security Object Document) in DER format from the identity document. |
54+
| `credential.verification_metadata` | `string` | Base64-encoded verification metadata from the original document check. |
55+
56+
```json
57+
{
58+
"identityCommitment": "0x000000000000000000000000000000000000000000000000000000000000000c",
59+
"sub": "0x000000000000000000000000000000000000000000000000000000000000002a",
60+
"credential": {
61+
"sod": "<base64-sod-der>",
62+
"verification_metadata": "<base64-json>"
63+
}
64+
}
65+
```
66+
67+
</Tab>
68+
<Tab title="MNC (My Number Card)">
69+
| Field | Type | Description |
70+
| ------------------- | -------- | ----------------------------------------------------------------- |
71+
| `credential.sd_jwt` | `string` | SD-JWT (Selective Disclosure JWT) from the MNC verification flow. |
72+
73+
```json
74+
{
75+
"identityCommitment": "0x000000000000000000000000000000000000000000000000000000000000000c",
76+
"sub": "0x000000000000000000000000000000000000000000000000000000000000002a",
77+
"credential": {
78+
"sd_jwt": "<sd-jwt-string>"
79+
}
80+
}
81+
```
82+
83+
</Tab>
84+
</Tabs>
85+
86+
### Response
87+
88+
#### Success response
89+
90+
```json
91+
{
92+
"result": {
93+
"credential": "<base64-encoded World ID v4 credential>"
94+
}
95+
}
96+
```
97+
98+
#### Error responses
99+
100+
| Status | Error | Description |
101+
| ------ | ------------------ | --------------------------------------------------------------------------- |
102+
| 400 | `invalid_data` | Request payload is malformed or missing required fields. |
103+
| 400 | `sub_mismatch` | `sub` does not match the one used in previous migrations for this identity. |
104+
| 400 | `document_expired` | The identity document has expired and cannot be used for migration. |
105+
| 401 | `unauthorized` | Authentication failed. |
106+
| 404 | `not_found` | No matching enrollment record found for this credential. |
107+
108+
## Planned Endpoints
109+
110+
### Enrollment <Badge disabled icon="lock" color="blue">Coming soon</Badge>
111+
112+
Details coming soon.
113+
114+
### Re-issuance <Badge disabled icon="lock" color="blue">Coming soon</Badge>
115+
116+
Details coming soon.
117+
118+
## Implementation Notes
119+
120+
<Note>
121+
This is advanced documentation about the internal workings of the NFC
122+
Credential and is not relevant for RP integration.
123+
</Note>
124+
125+
### Associated Data
126+
127+
The associated data of this credential contains different data groups found in the original document. More information coming soon.
128+
129+
{/* TODO: Add details on the PCP */}
130+
131+
#### Associated Data Commitment
132+
133+
To ensure the associated data has guaranteed integrity and can be re-used in the future for credential re-issuance, the commitment is computed as follows:
134+
135+
1. For ICAO-9303 documents, the message digest of the `EF.SOD` signature is used. The message digest is obtained from `SignedData.SignerInfos[0].SignedAttrs` where the signed attribute for the digest is identified by the Object Identifier `1.2.840.113549.1.9.4`. This digest is then hashed with the `blake3` hashing function from the raw bytes. Finally, the `blake3` hash is converted to a field element with modulo reduction.
136+
2. Information on MNC documents coming soon.

0 commit comments

Comments
 (0)