# Signature components and metadata

To calculate the signature value for the request, the caller must prepare the signature base string and generate a signature of it with one of the supported signing algorithms.

## Signature base string

The signature base string consists of several components, each of which is defined as a key-value pair. For each component, key and value are separated by a colon followed by a space (`: `). All components are separated by newline characters (`\n`, i.e. ASCII 0x0a).

**Example**


```http
component-key: component-value
```

Please note that for version v6, Upvest does **not** enclose the component-key in double quotes, in contrast to [the IETF draft v6](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures-06#name-http-message-components).

This is a bug which we can not fix in order to stay backwards-compatible with early adopters.

## Signature components

To calculate the signature for a request to the Investment API, use the
following list of components:

| Component key | Description | Documentation | Example |
|  --- | --- | --- | --- |
| `@method` | HTTP method of a request message.  **NOTE**: Must be UPPERCASE. | [Link](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures-06#name-method) | `@method: POST` |
| `@path` | Target path of the HTTP request message. | [Link](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures-06#name-path) | `@path: /endpoint` |
| `@query` | Query component of the HTTP request message including '?' character.  **NOTE**: For requests without query parameters, you must exclude this component entirely. | [Link](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures-06#name-query) | `@query: ?param=value&foo-bar` |
| `accept` | HTTP header with expected media type of reponse. | [Link](https://datatracker.ietf.org/doc/html/rfc2616#section-14.1) | `accept: application/json` |
| `authorization` | HTTP header with authentication token.  **NOTE**: This component must be used for all requests except the [access token request](/api/access-tokens/issue_token). | [Link](/products/byol/concepts/api_concepts/authentication/authentication_oauth) | `authorization: Bearer {access-token}` |
| `content-length` | HTTP header with the byte size of the entire HTTP request body.  **NOTE**: Only requests with a request body must contain this component. | [Link](https://datatracker.ietf.org/doc/html/rfc2616#section-14.13) | `content-length: 15` |
| `content-type` | HTTP header with media type of the HTTP request body.  **NOTE**: Only requests with a request body must contain this component. | [Link](https://datatracker.ietf.org/doc/htmlrfc2616#section-14.17) | `content-type: application/json` |
| `digest` | HTTP header with a checksum of the entire HTTP request body.  **NOTE**: Only requests with a request body must contain this component. | [Link](https://datatracker.ietf.org/dochtml/draft-ietf-httpbis-digest-headers-10) | `digest: SHA-256=6alpwuzt6j/qxb25kIuW6T1vsr57nLFFAXP+VOlhTlg=` |
| `idempotency-key` | HTTP header with an idempotency key.  **NOTE**: Only for certain API endpoints, see [documentation](/products/byol/concepts/api_concepts/idempotency) | [Link](/products/byol/concepts/api_concepts/idempotency) | `idempotency-key: 424e8603-f12c-4a58-8eb1-5edfe471f3ab` |
| `upvest-client-id` | HTTP header with your client ID. | [Link](/products/byol/concepts/api_concepts/authentication/authentication_http_message_signatures) | `upvest-client-id: 0df8d466-857d-443f-b411-a1b27b5db42e` |


Please note that the order of the component keys in the signature base string must be the same as the order in the `@signature-params` component itself, and in the `signature` header.

The component `@signature-params` contains several pieces of [signature metadata](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures-06#name-signature-parameters), separated by semicolons (`;`).

**Example**


```http
@signature-params: ("@method" "@path" "@query" "accept" "authorization" "content-length" "content-type" "digest" "idempotency-key" "upvest-client-id");keyid="8d4997a8-cf7a-4e51-adbb-401656a3e5c2";created=1633529659;expires=1633529664;nonce="o085M4cMgpbicuOL"
```

The signature metadata consists of the following parts:

| Component | Description | Example |
|  --- | --- | --- |
| List of components keys | Component keys (see 'List of signature components' above) are enclosed in double quotes `"`, separated by single spaces `" "`, and the entire list of component keys enclosed in parantheses `("..." "...")`. | `("@method" "@path" "@query" "accept" "authorization" "content-length" "content-type" "digest" "idempotency-key" "upvest-client-id")` |
| `keyid` | Unique identifier of the signing key. | `keyid="8d4997a8-cf7a-4e51-adbb-401656a3e5c2"` |
| `created` | The creation date of the request, which is the same value as in the `Date` header of the request, but in **unixtime format**. As a number, the value is not quoted. | `created=1633529659` |
| `expires` | **Optional**. The expiration date of the request, which is the same value as in the `Expires` header of the request, but in **unixtime format**. As a number, the value is not quoted. | `expires=1633529664` |
| `nonce` | A unique random value, which is generated for this signature. | `nonce="o085M4cMgpbicuOL"` |


Although the `@signature-params` component itself is a mandatory part of the signature base string, it is **not included** in the list of components keys, [as mentioned in the IETF draft](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures-06#name-signature-parameters).