Signature Components and Metadata (v15)
To calculate the signature value for the request, the caller must prepare the signature base string from a number of components. You will generate a signature, using the base string, 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, the key is enclosed in double quotes (") and 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
"component-key": component-valueSignature 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 | "@method": POST |
@path | Target path of the HTTP request message. | Link | "@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 | "@query": ?param=value&foo-bar |
accept | HTTP header with expected media type of reponse. | Link | "accept": application/json |
authorization | HTTP header with authentication token. NOTE: This component must be used for all requests except the access token request. | [Link]/documentation/concepts/api_concepts/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 | "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 | "content-type": application/json |
content-digest | HTTP header with a checksum of the entire HTTP request body. NOTE: Only requests with a request body must contain this component. | Link | "content-digest": sha-512=:Hd9/AvGZkbjitW1+Ml8Fg1ux1mtcDYe6mLQjDyoowIWa3LM/PmwN2v9O+MjtQGrCA3EQWUL54dlgxKHyYbrucw==: |
idempotency-key | HTTP header with an idempotency key. NOTE: Only for certain API endpoints, see [documentation]/documentation/concepts/api_concepts/idempotency/). | [Link]/documentation/concepts/api_concepts/idempotency/) | "idempotency-key": 424e8603-f12c-4a58-8eb1-5edfe471f3ab |
upvest-client-id | HTTP header with your client ID. | [Link]/documentation/concepts/api_concepts/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.
Metadata of the @signature-params component
The component @signature-params contains several pieces of signature metadata, separated by semicolons (;).
Example
"@signature-params": ("@method" "@path" "@query" "accept" "authorization" "content-length" "content-type" "content-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.