Sign Portal.io API Requests with HMAC-SHA256

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. The AI Builder upload-content endpoint uses multipart/form-data — and for multipart, the value used in the signing string must include the full boundary=<value> parameter, not just multipart/form-data (see Sign multipart requests below). 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.

Sign multipart requests

For multipart/form-data requests, the content type segment of the canonical message must include the full boundary=<value> parameter — the same value you send in the Content-Type header on the wire. For an upload to POST /public/api/proposals/{ProposalId}/ai/content, the canonical message looks like this:

POSThttps://api.portal.io/public/api/proposals/12345/ai/contentmultipart/form-data; boundary=PortalBoundary1748392012345Mon, 06 Apr 2026 00:22:19 GMTqBOSOYDeZaSzTxqMCL1Kr66JpU2H6wHCLz7xviZUOcA=

Breaking that down:

Method: POST
Base URL: https://api.portal.io/public/api/proposals/12345/ai/content
Content type: multipart/form-data; boundary=PortalBoundary1748392012345
Timestamp: Mon, 06 Apr 2026 00:22:19 GMT
User API key: qBOSOYDeZaSzTxqMCL1Kr66JpU2H6wHCLz7xviZUOcA=

Use the same boundary string in both the Content-Type header you send and the canonical message you sign. Most HTTP clients generate a random boundary internally and don’t expose it. To work around this, either pre-build the multipart body and Content-Type yourself before signing, or use a client like Python’s requests-toolbelt.MultipartEncoder that lets you fix the boundary at construction time. The full request body (form fields and file parts) is still not included in the canonical message — only the content type with the boundary parameter is.

If a multipart endpoint is called with a query string (for example ?isMultiChunkUpload=true), the canonical message still uses the base URL without the query string, following the same rule as every other Portal.io endpoint.

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.

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

const crypto = require('crypto');

function signRequest(method, url, contentType, timestamp, userKey, secretKey) {
  // Strip query string — only scheme + host + path are signed
  const baseUrl = new URL(url);
  baseUrl.search = '';
  const urlForSigning = baseUrl.toString().replace(/\/$/, '');

  // Build canonical message
  let parts = [method.toUpperCase(), urlForSigning];
  if (method.toUpperCase() !== 'GET') {
    parts.push(contentType);
  }
  parts.push(timestamp, userKey);
  const canonical = parts.join('');

  // Compute HMAC-SHA256
  // Use secretKey as raw ASCII bytes — do NOT base64-decode it first
  const hmac = crypto.createHmac('sha256', Buffer.from(secretKey, 'ascii'));
  hmac.update(canonical, 'utf8');
  return hmac.digest('base64');
}

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.

Get Started

Authentication

Concepts

Sign Portal.io API Requests with HMAC-SHA256

Canonical message format

Rules

Examples

GET request (credential exchange)

GET request (with query parameters)

POST request (adding an area to a proposal)

Sign multipart requests

Computing the signature

Full request example

​Canonical message format

​Rules

​Examples

​GET request (credential exchange)

​GET request (with query parameters)

​POST request (adding an area to a proposal)

​Sign multipart requests

​Computing the signature

​Full request example

Canonical message format

Rules

Examples

GET request (credential exchange)

GET request (with query parameters)

POST request (adding an area to a proposal)

Sign multipart requests

Computing the signature

Full request example