# Metadata API

The Azion Runtime Metadata API gives a function a set of values about each request: the GeoIP location of the client, its address and port, the protocol, the TLS session, fingerprints, and identifiers. Functions that run on an Application or on a Firewall can read it. Use it to filter and manage access to your application, or to apply different logic for each scenario.

> **Note**
>
> Under `azion dev`, the metadata object is `undefined`. Test metadata reads on a deployed function.

---

## Access

The metadata is an object on the request. With the `export default { fetch }` handler, read it from `request.metadata`:

```javascript
const ip = request.metadata["remote_addr"];
```

With `addEventListener("fetch", ...)` or `export default main`, read it from `event.request.metadata`:

```javascript
let ip = event.request.metadata["remote_addr"];
```

Every value is a string or `null`.

---

## GeoIP

The GeoIP keys locate the client from its IP address.

| Key                         | Description                         |
| --------------------------- | ----------------------------------- |
| `geoip_asn`                 | Autonomous system number.           |
| `geoip_city`                | City code.                          |
| `geoip_city_continent_code` | Continent code of the city.         |
| `geoip_city_country_code`   | Country code of the city.           |
| `geoip_city_country_name`   | Country name of the city.           |
| `geoip_continent_code`      | Continent code, for example `SA`.   |
| `geoip_country_code`        | Country code, for example `BR`.     |
| `geoip_country_name`        | Country name, for example `Brazil`. |
| `geoip_region`              | Region code.                        |
| `geoip_region_name`         | Region name.                        |

---

## Remote

The remote keys describe the client connection.

| Key           | Description                                                                                                |
| ------------- | ---------------------------------------------------------------------------------------------------------- |
| `remote_addr` | IP address of the client.                                                                                  |
| `remote_port` | TCP port of the client.                                                                                    |
| `remote_user` | User given in the URL, for example `user` in `https://user@example.com/`. `null` when the URL has no user. |

---

## Server

The server key names the protocol of the request.

| Key               | Description                                      |
| ----------------- | ------------------------------------------------ |
| `server_protocol` | Protocol of the request, for example `HTTP/2.0`. |

---

## TLS

The TLS keys describe the TLS session of the request.

| Key            | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| `ssl_cipher`   | TLS cipher of the session, for example `TLS_AES_256_GCM_SHA384`. |
| `ssl_protocol` | TLS protocol of the session, for example `TLSv1.3`.              |

---

## Fingerprints

The fingerprint keys carry TLS and HTTP fingerprints for security analysis.

| Key                       | Description                         |
| ------------------------- | ----------------------------------- |
| `server_fingerprint`      | Server TLS fingerprint.             |
| `server_fingerprint_ja4h` | Server JA4H fingerprint.            |
| `http_ssl_ja4`            | JA4 TLS fingerprint of the request. |
| `client_fingerprint`      | Client fingerprint, or `null`.      |

---

## Identifiers

The identifier keys name the account and the resources that handle the request.

| Key                | Description                                                                                                                 |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `solution_id`      | Internal identifier of the solution (bundle of products) that handles the request.                                          |
| `client_id`        | Identifier of the Azion account that owns the workload.                                                                     |
| `function_id`      | Identifier of the function that runs for the request.                                                                       |
| `configuration_id` | Identifier of the workload that received the request.                                                                       |
| `virtualhost_id`   | The workload identifier followed by the `client_id`.                                                                        |
| `connector_id`     | Identifier of the connector, when the request goes through one. A dash (`-`) when no connector is involved.                 |
| `request_id`       | Unique ID of the request, the same value as the `x-azion-request-id` response header. Use it to trace a request end to end. |

---

## Example

This function returns the whole metadata object of the request as JSON:

```javascript
addEventListener("fetch", (event) => {
  const metadata = event.request.metadata;
  event.respondWith(new Response(JSON.stringify(metadata, null, 1), {
    headers: { "content-type": "application/json" },
  }));
});
```

A request to the deployed function returns the object below. The client address is a documentation address and the city is a placeholder:

```json
{
 "server_fingerprint": "t13d4007h2_731077d8320c_7395dae3b2f3",
 "server_fingerprint_ja4h": "ge20nn030000_b5531655046c_e3b0c44298fc_e3b0c44298fc",
 "client_fingerprint": null,
 "http_ssl_ja4": "t13d4007h2_731077d8320c_7395dae3b2f3",
 "geoip_asn": "64496",
 "geoip_city": "<city>",
 "geoip_city_continent_code": "SA",
 "geoip_city_country_code": "BR",
 "geoip_city_country_name": "Brazil",
 "geoip_continent_code": "SA",
 "geoip_country_code": "BR",
 "geoip_country_name": "Brazil",
 "geoip_region": "<region>",
 "geoip_region_name": "<region-name>",
 "remote_addr": "192.0.2.10",
 "remote_port": "5710",
 "remote_user": null,
 "server_protocol": "HTTP/2.0",
 "ssl_cipher": "TLS_AES_256_GCM_SHA384",
 "ssl_protocol": "TLSv1.3",
 "solution_id": "1531930033",
 "client_id": "1234u",
 "function_id": "12345",
 "configuration_id": "1234567890",
 "virtualhost_id": "12345678901234u",
 "connector_id": "-",
 "request_id": "0123456789abcdef0123456789abcdef"
}
```

---

## Related resources

- [Network List API](/en/documentation/devtools/runtime/api-reference/network-list.md): Check whether the `remote_addr` of a request is in one of your network lists.
- [Handlers](/en/documentation/devtools/runtime/api-reference/handlers.md): The handler shapes a function exports, and the request each one receives.
- [Functions](/en/documentation/platform/functions.md): How a function is created, instantiated on an application or a firewall, and invoked by a rule.
- [Functions for Firewall](/en/documentation/platform/firewall/functions.md): The event and methods a function on a Firewall uses to allow, deny, drop, or answer a request.