Sign Portal.io API Requests with HMAC-SHA256

Step-by-step guide to building the canonical message and computing the HMAC-SHA256 signature required on every Portal.io API request.

Every Portal.io API request must include an X-MSS-SIGNATURE header containing a Base64-encoded HMAC-SHA256 signature. The signature is computed from a canonical message you build from properties of the request itself, then signed using your Secret Key. This page explains exactly how to construct the canonical message and compute the signature.

Canonical message format

The canonical message is a single string formed by concatenating these components with no separator:

For GET requests:

[HTTP method][base URL][timestamp][user API key]

For POST, PUT, and other non-GET requests:

[HTTP method][base URL][content type][timestamp][user API key]

The components map to your request as follows:

• HTTP method — uppercase, e.g. GET, POST, PUT
• Base URL — the scheme, host, and path only. Do not include query parameters. For example, use https://api.portal.io/public/proposals even if the actual request URL has ?PageNumber=1&PageSize=10 appended.
• Content type — the exact value of the Content-Type header. Include this segment only for non-GET requests. Most Portal.io POST endpoints use application/x-www-form-urlencoded. The AI Builder endpoints (generate-outline and build-proposal) use application/json. Always check the endpoint’s documentation for the correct value — the content type in your signing string must match the Content-Type header exactly or the request will fail with 401.
• Timestamp — the exact value you send in X-MSS-CUSTOM-DATE
• User API key — the exact value you send in X-MSS-API-USERKEY

Rules

• Use the base URL without query parameters. This is by design — query parameters are sent in the request as normal, but the server intentionally excludes them from signature verification. Only the scheme, host, and path are signed.
• For GET requests, omit the content-type segment completely. Do not include an empty string in its place.
• For non-GET requests, include the exact Content-Type value from the request header. The value in the signing string and the value in the header must match exactly — including case and any suffixes (e.g. application/x-www-form-urlencoded, not Application/X-WWW-Form-Urlencoded).
• The request body is not part of the canonical message. Only the content type is included, not the body itself.
• The timestamp must exactly match the value in X-MSS-CUSTOM-DATE, character for character.
• The user API key must exactly match the value in X-MSS-API-USERKEY, character for character.
• For the initial credential exchange, the user API key is an empty string in both the header and the canonical message.

Do NOT Base64-decode the Secret Key before computing the HMAC. Use it exactly as provided — as raw ASCII bytes. Base64-decoding the key before use is a common mistake that produces an invalid signature.

Examples

GET request (credential exchange)

For the initial credential exchange, where the user API key is empty, the canonical message looks like this:

GEThttps://api.portal.io/authenticate/apikeyexchangeMon, 06 Apr 2026 00:22:19 GMT

Breaking that down:

• Method: GET
• Base URL: https://api.portal.io/authenticate/apikeyexchange
• Content type: (omitted — this is a GET request)
• Timestamp: Mon, 06 Apr 2026 00:22:19 GMT
• User API key: (empty string — this is the initial exchange)

Note that the actual HTTP request includes query parameters (?UserName=...&Password=...), but the canonical message uses only the base URL without them.

GET request (with query parameters)

When listing proposals with pagination, the canonical message is:

GEThttps://api.portal.io/public/proposalsMon, 06 Apr 2026 00:22:19 GMTqBOSOYDeZaSzTxqMCL1Kr66JpU2H6wHCLz7xviZUOcA=

The actual request URL includes ?PageNumber=1&PageSize=10, but those query parameters are not in the signed string.

POST request (adding an area to a proposal)

For a POST request, the content type is included between the URL and the timestamp:

POSThttps://api.portal.io/public/proposals/1042/areaapplication/x-www-form-urlencodedMon, 06 Apr 2026 00:22:19 GMTqBOSOYDeZaSzTxqMCL1Kr66JpU2H6wHCLz7xviZUOcA=

Breaking that down:

• Method: POST
• Base URL: https://api.portal.io/public/proposals/1042/area
• Content type: application/x-www-form-urlencoded
• Timestamp: Mon, 06 Apr 2026 00:22:19 GMT
• User API key: qBOSOYDeZaSzTxqMCL1Kr66JpU2H6wHCLz7xviZUOcA=

The request body (Name=Living+Room) is sent normally but is not part of the canonical message.

Computing the signature

Once you have the canonical message, compute the HMAC-SHA256 using your Secret Key as raw ASCII bytes, then Base64-encode the raw digest.

python

import hmac
import hashlib
import base64
from urllib.parse import urlsplit, urlunsplit

def sign_request(method, url, content_type, timestamp, user_key, secret_key):
    # Strip query string — only scheme + host + path are signed
    parts = urlsplit(url)
    base_url = urlunsplit((parts.scheme, parts.netloc, parts.path, '', ''))

    # Build canonical message
    message_parts = [method.upper(), base_url]
    if method.upper() != "GET":
        message_parts.append(content_type)
    message_parts.append(timestamp)
    message_parts.append(user_key)
    canonical = "".join(message_parts)

    # Compute HMAC-SHA256
    # Use secret_key as raw ASCII bytes — do NOT base64-decode it first
    signature = hmac.new(
        secret_key.encode("ascii"),
        canonical.encode("utf-8"),
        hashlib.sha256
    ).digest()

    return base64.b64encode(signature).decode("ascii")

Full request example

Here is how the computed signature fits into a complete request. This example performs the initial credential exchange:

curl -i -X GET \
  "https://sandbox.api.portal.io/authenticate/apikeyexchange?UserName=user%40example.com&Password=MyP%40ss123" \
  -H "Accept: application/json" \
  -H "X-MSS-API-APPID: YOUR_APP_ID" \
  -H "X-MSS-API-USERKEY: " \
  -H "X-MSS-CUSTOM-DATE: Mon, 06 Apr 2026 00:22:19 GMT" \
  -H "X-MSS-SIGNATURE: BASE64_HMAC_SIGNATURE"

Replace BASE64_HMAC_SIGNATURE with the output of your signing function. Replace YOUR_APP_ID with your API Application Key. The X-MSS-API-USERKEY header is intentionally empty for this call.

Once you have your User API Key, include it in both X-MSS-API-USERKEY and your canonical message on all subsequent requests.