Skip to main content

Create a signed URL request

For details on how you can validate these URL requests, see Validate external link requests from Maxsight.

The following URL query parameters are used in this order to create the signed URL request:

Parameter

Description

Example

version

Versioning information for the signed URL. At present, this will always be set to 1.

1

valid_until

The epoch time the URL is considered valid until. Requests after this time are deemed invalid by your integration. Currently this time is set to 5 minutes after the request time. The format of this field is in Unix timestamp, which is the number of seconds since 1 January 1970 at 00:00:00 UTC.

1710269146

auditee_id

UUID identifying the user or API key that has used the URL link.

59fcb6e0-0a7f-4d09-ad55-1b331109218

signature

A Base64 url safe encoding of the SHA-256 HMAC of the entire URL, excluding the signature parameter.

t7d2xHkwX14KSy5MCYYxwS0QTNjrfWN63X5ZkQ313Wc%3D

To create a signed URL request:

  1. Add the version. This is presently always set to 1.

  2. Add the valid_until value. This is set to 5 minutes after the request time. The format of this field is in Unix timestamp, which is the number of seconds since 1 January 1970 at 00:00:00 UTC.

  3. Add the auditee_id. Maxsight gets this value from the API key of the user in Maxsight.

  4. Sign the entire URL and query parameters as per steps 1, 2, and 3. This is done by taking the entire URL and creating a SHA-256 HMAC using the shared SECRET_KEY.

    The resulting value is used as the signature value described below.

    The following is an example of how this might look:

    Partner_Experience_create_signed_URL_request_signature_value_example.png

  5. Add the signature as a query parameter to the URL.

    An example signed URL request could look like the following: http://www.example.com/?version=1&valid_until=1710269146&auditee_id=59fcb6e0-0a7f-4d09-ad55-1b331109218d&signature=t7d2xHkwX14KSy5MCYYxwS0QTNjrfWN63X5ZkQ313Wc%3D

Code example

The following example shows how a signed URL request could be received and validated using Python:

import re
import base64
import hashlib
import hmac
from urllib.parse import urlparse, parse_qs

# this would be your live integration secret key as shared with platform
SECRET_KEY = '<YOUR-SECRET-KEY>'
# this is an example of how a signed url would look
SIGNED_URL = 'https://your-integration-url.com/?version=1&valid_until=1697821049&auditee_id=b1646de6-17eb-4733-a1eb-0d69590364d0&signature=0MtEEuERQqnCNQhipvo7vgeZq5PH2n-C8_Wh5Sa4jUc='

# strip the &signature=<text> from the request URL
url_no_sig = re.sub(r'&signature=.*', '', SIGNED_URL)

# get the signature value from the signature parameter in the request
parsed_url = urlparse(SIGNED_URL)
query_params = parse_qs(parsed_url.query)
query_signature_value = query_params["signature"][0]

# decode your secret key, note: NOT URL SAFE
decoded_secret_key = base64.b64decode(SECRET_KEY)

# compute a signature based on the url with the decoded secret key
# this is computing the value that came in the request signature parameter
computed_signature = hmac.new(decoded_secret_key, url_no_sig.encode(), hashlib.sha256).digest()
# decode the signature from the signature request parameter, note: URL SAFE
expected_signature = base64.urlsafe_b64decode(query_signature_value)

# compare the two signatures to ensure they are equal
assert(computed_signature == expected_signature)

The following shows how the valid_until value could be created using Python:

from datetime import datetime, timedelta
import pytz

# get the current time in UTC plus 5 minutes
time_plus_five_minutes = datetime.now(pytz.utc) + timedelta(minutes=5)
# convert this to the Unix timestamp format
valid_until = int(time_plus_five_minutes.timestamp())

Additional information

In this section: