Signature Components and Metadata (v6)

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

component-key: component-value
WARNING

Please note that for version v6, Upvest does not enclose the component-key in double quotes, in contrast to the IETF draft v6.

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 keyDescriptionDocumentationExample
@methodHTTP method of a request message.
NOTE: Must be UPPERCASE.
Link@method: POST
@pathTarget path of the HTTP request message.Link@path: /endpoint
@queryQuery 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
acceptHTTP header with expected media type of reponse.Linkaccept: application/json
authorizationHTTP 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-lengthHTTP header with the byte size of the entire HTTP request body.
NOTE: Only requests with a request body must contain this component.
Linkcontent-length: 15
content-typeHTTP header with media type of the HTTP request body.
NOTE: Only requests with a request body must contain this component.
Linkcontent-type: application/json
digestHTTP header with a checksum of the entire HTTP request body.
NOTE: Only requests with a request body must contain this component.
Linkdigest: SHA-256=6alpwuzt6j/qxb25kIuW6T1vsr57nLFFAXP+VOlhTlg=
idempotency-keyHTTP 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-idHTTP header with your client ID.[Link]/documentation/concepts/api_concepts/authentication/http_message_signatures)upvest-client-id: 0df8d466-857d-443f-b411-a1b27b5db42e
NOTE

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, separated by semicolons (;).

Example

@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:

ComponentDescriptionExample
List of components keysComponent 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")
keyidUnique identifier of the signing key.keyid="8d4997a8-cf7a-4e51-adbb-401656a3e5c2"
createdThe 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
expiresOptional. 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
nonceA unique random value, which is generated for this signature.nonce="o085M4cMgpbicuOL"
NOTE

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.


Was this page helpful?