Authenticating Requests

Authenticated requests require a signature that you create by using your access key and secret key.

Data in transit protection

To prevent tampering a request while it is in transit, we use some of the request elements to calculate the request signature. Upon receiving the request, DaVinciNT calculates the signature by using the same request elements. If any request component does not match the component that was used to calculate the signature, the request will be rejected.

Protect against reuse of the signed portions of the request

The signed parts of requests are valid within 2 minutes of the timestamp in the request. An unauthorized party who has access to a signed request can modify the unsigned payload of the request without affecting the request's validity in the 2-minute window. Because of this, we recommend that you maximize protection by signing url and body (payload), making HTTPS requests to DaVinciNT, and by using the x-nt-content-sha256 header to require users to sign request bodies.

Header

Authorization: DirectGrant [username] [accessKey] [utcDate(yyyyMMddHHmmss)] [signature]

To include payload in signature:

x-nt-content-sha256: true

Signing Requests

Authentication information that you send in a request must include a signature. To calculate a signature, you first concatenate select request elements to form a string, referred to as the string to sign. You then use a signing key to calculate the hash-based message authentication code (HMAC) of the string to sign.

Signature Calculations:

To calculate a signature, you first need a string to sign. You then calculate a HMAC-SHA256 hash of the string to sign by using a secret key. When DaVinciNT receives an authenticated request, it computes the signature and then compares it with the signature that you provided in the request.

Signature: HMAC-SHA256(UtcDate("yyyyMMddHHmmss") +  HttpVerb(Uppercase) + PathAndQueryString(Uppercase) + Bodyhash(optional))

  1. UtcDate: The timeStamp is the current UTC time - format: "yyyyMMddHHmmss": e.g. 20210118093334
  2. HttpVerb: POST|PUT|DELETE...
  3. PathAndQueryString: e.g.: /TD/TRAVEL-INFOS/4711?Q=100
  4. Bodyhash: SHA256Hash - secure hash algorithm
  5. HMAC-SHA256: Computes HMAC by using the SHA256 algorithm with the secret key provided. This is the final signature.

When transferring payload you can optionally choose to include the payload hash (Bodyhash) in the signature calculations. Then you need to set the header.

- Signed payload: Set header: "x-nt-content-sha256: true" when sending the request.

Example

Authorization: DirectGrant test@davincint-test.de public1234 20210118093334 C8P/6j4En8+pqLA9gcQmih7rU119s/F9iMCHZMBxPOc=

x-nt-content-sha256: true