# Identity Fields

This page defines the set of verified identity fields used across Skyfire APIs.

These fields are shared between:

* `humanIdentityRequirement` (used in **[Create Agent's Service](https://docs.skyfire.xyz/reference/create-agents-service)**)
* `identityPermissions` (used in **[Create Token](https://docs.skyfire.xyz/reference/create-token)**)

> **Key idea:**\
> Any field that can be required via `humanIdentityRequirement` can also be requested via `identityPermissions`.

***

## How These Fields Are Used

### `humanIdentityRequirement` (Service-level)

Defines **which identity fields a buyer must have verified** to access a service.

* Configured by the **seller**
* Acts as an **access requirement**

For example, a seller may require users to have verified their birthdate and family name before allowing token creation to their service. This could look like:

```http
POST https://api.skyfire.xyz/api/v1/agents/seller-services
skyfire-api-key: {{SELLER_API_KEY}}
content-type: application/json

{
  "name": "Weather Data API Service",
  "description": "Provides real-time weather data and forecasts for global locations. Includes current conditions, 7-day forecasts, and historical weather data.",
  "tags": [
    "weather",
    "api",
    "data"
  ],
  "type": "API",
  "price": "0.01",
  "openApiSpecUrl": "https://example.com/openapi.json",
  "priceModel": "PAY_PER_USE",
  "minimumTokenAmount": "0.01",
  "humanIdentityRequirement": {
    "individual": ["birthdate", "family_name"],
    "organization": ["birthdate", "family_name"]
  }
}
```

***

### `identityPermissions` (Token-level)

Defines **which verified identity fields are included in a token**.

* Requested by the **buyer**
* Controls what data is **shared with the seller**

For example, a buyer may want to ensure their first name is included in a token for tracking purposes. This could look like:

```http
POST {{baseUrl}}/api/v1/tokens
skyfire-api-key: {{VERIFIED_BUYER_API_KEY}}
content-type: application/json

{
  "type": "kya",
  "sellerServiceId": "94d8beab-a134-48d5-8353-bd8a67eab40b",
  "identityPermissions": ["given_name"]
}
```

***

# Identity Types

A Skyfire user may be:

* `"individual"`
* `"organization"`

Each type supports a defined set of identity fields.

## Individual

### Level 1 (Basic Identity)

| Field Name           | Type     |
| -------------------- | -------- |
| `birthdate`          | `string` |
| `given_name`         | `string` |
| `middle_name`        | `string` |
| `family_name`        | `string` |
| `phone_number`       | `string` |
| `phone_country_code` | `string` |

### Level 2 (Extended Identity)

Includes all **Level 1 fields**, plus:

| Field Name               | Type     |
| ------------------------ | -------- |
| `id_document.issued_on`  | `string` |
| `id_document.expires_on` | `string` |
| `id_document.issued_by`  | `string` |
| `address-full`           | `string` |
| `address-city`           | `string` |
| `address-region`         | `string` |
| `address-country`        | `string` |
| `no-address`             | `string` |

> **Note:** Level 2 verification automatically includes all Level 1 fields.

<br />

## Organization

| Field Name                                | Type     |
| ----------------------------------------- | -------- |
| `organization_name`                       | `string` |
| `organization_tax_id`                     | `string` |
| `organization_physical_address-full`      | `string` |
| `organization_physical_address-city`      | `string` |
| `organization_physical_address-region`    | `string` |
| `organization_physical_address-country`   | `string` |
| `no-organization_physical_address`        | `string` |
| `organization_registered_address-full`    | `string` |
| `organization_registered_address-city`    | `string` |
| `organization_registered_address-region`  | `string` |
| `organization_registered_address-country` | `string` |
| `no-organization_registered_address`      | `string` |
| `birthdate`                               | `string` |
| `given_name`                              | `string` |
| `middle_name`                             | `string` |
| `family_name`                             | `string` |
| `phone_number`                            | `string` |
| `phone_country_code`                      | `string` |

<br />