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-value

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	`"@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`

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.

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"`

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.

On this page