Exchange Credentials for a User API Key

url="https://sandbox.api.portal.io/authenticate/apikeyexchange?UserName=user%40example.com&Password=MyP%40ss123"
base_url="https://sandbox.api.portal.io/authenticate/apikeyexchange"
timestamp="$(date -u '+%a, %d %b %Y %H:%M:%S GMT')"
canonical="GET${base_url}${timestamp}"
signature="$(printf '%s' "$canonical" | openssl dgst -sha256 -hmac 'YOUR_SECRET_KEY' -binary | base64)"

curl -i -X GET \
  "$url" \
  -H "Accept: application/json" \
  -H "X-MSS-API-APPID: YOUR_APP_ID" \
  -H "X-MSS-API-USERKEY: " \
  -H "X-MSS-CUSTOM-DATE: $timestamp" \
  -H "X-MSS-SIGNATURE: $signature"

import requests
from datetime import datetime, timezone
from email.utils import format_datetime
from portal_auth import sign_request  # See authentication guide

url = "https://sandbox.api.portal.io/authenticate/apikeyexchange?UserName=user%40example.com&Password=MyP%40ss123"
timestamp = format_datetime(datetime.now(timezone.utc), usegmt=True)
signature = sign_request("GET", url, "", timestamp, "", "YOUR_SECRET_KEY")

response = requests.get(url, headers={
    "Accept": "application/json",
    "X-MSS-API-APPID": "YOUR_APP_ID",
    "X-MSS-API-USERKEY": "",
    "X-MSS-CUSTOM-DATE": timestamp,
    "X-MSS-SIGNATURE": signature
})
print(response.json())

const { signRequest } = require('./portalAuth'); // See authentication guide

const url = "https://sandbox.api.portal.io/authenticate/apikeyexchange?UserName=user%40example.com&Password=MyP%40ss123";
const timestamp = new Date().toUTCString();
const signature = signRequest("GET", url, "", timestamp, "", "YOUR_SECRET_KEY");

const response = await fetch(url, {
    headers: {
        "Accept": "application/json",
        "X-MSS-API-APPID": "YOUR_APP_ID",
        "X-MSS-API-USERKEY": "",
        "X-MSS-CUSTOM-DATE": timestamp,
        "X-MSS-SIGNATURE": signature
    }
});
const data = await response.json();
console.log(data);

{
  "userId": "string",
  "sessionId": "string",
  "userName": "string",
  "displayName": "string",
  "bearerToken": "string",
  "refreshToken": "string",
  "refreshTokenExpiry": "2026-04-06T00:22:19Z",
  "profileUrl": "string",
  "roles": ["string"],
  "permissions": ["string"],
  "authProvider": "string",
  "meta": {
    "apiKey": "YOUR_USER_API_KEY"
  }
}

GET

authenticate

apikeyexchange

url="https://sandbox.api.portal.io/authenticate/apikeyexchange?UserName=user%40example.com&Password=MyP%40ss123"
base_url="https://sandbox.api.portal.io/authenticate/apikeyexchange"
timestamp="$(date -u '+%a, %d %b %Y %H:%M:%S GMT')"
canonical="GET${base_url}${timestamp}"
signature="$(printf '%s' "$canonical" | openssl dgst -sha256 -hmac 'YOUR_SECRET_KEY' -binary | base64)"

curl -i -X GET \
  "$url" \
  -H "Accept: application/json" \
  -H "X-MSS-API-APPID: YOUR_APP_ID" \
  -H "X-MSS-API-USERKEY: " \
  -H "X-MSS-CUSTOM-DATE: $timestamp" \
  -H "X-MSS-SIGNATURE: $signature"

import requests
from datetime import datetime, timezone
from email.utils import format_datetime
from portal_auth import sign_request  # See authentication guide

url = "https://sandbox.api.portal.io/authenticate/apikeyexchange?UserName=user%40example.com&Password=MyP%40ss123"
timestamp = format_datetime(datetime.now(timezone.utc), usegmt=True)
signature = sign_request("GET", url, "", timestamp, "", "YOUR_SECRET_KEY")

response = requests.get(url, headers={
    "Accept": "application/json",
    "X-MSS-API-APPID": "YOUR_APP_ID",
    "X-MSS-API-USERKEY": "",
    "X-MSS-CUSTOM-DATE": timestamp,
    "X-MSS-SIGNATURE": signature
})
print(response.json())

const { signRequest } = require('./portalAuth'); // See authentication guide

const url = "https://sandbox.api.portal.io/authenticate/apikeyexchange?UserName=user%40example.com&Password=MyP%40ss123";
const timestamp = new Date().toUTCString();
const signature = signRequest("GET", url, "", timestamp, "", "YOUR_SECRET_KEY");

const response = await fetch(url, {
    headers: {
        "Accept": "application/json",
        "X-MSS-API-APPID": "YOUR_APP_ID",
        "X-MSS-API-USERKEY": "",
        "X-MSS-CUSTOM-DATE": timestamp,
        "X-MSS-SIGNATURE": signature
    }
});
const data = await response.json();
console.log(data);

{
  "userId": "string",
  "sessionId": "string",
  "userName": "string",
  "displayName": "string",
  "bearerToken": "string",
  "refreshToken": "string",
  "refreshTokenExpiry": "2026-04-06T00:22:19Z",
  "profileUrl": "string",
  "roles": ["string"],
  "permissions": ["string"],
  "authProvider": "string",
  "meta": {
    "apiKey": "YOUR_USER_API_KEY"
  }
}

The API key exchange endpoint authenticates your Portal.io credentials and returns a meta.apiKey value you must include in the X-MSS-API-USERKEY header on all subsequent requests. This is the entry point for every integration: call it once to obtain the key, then use that key to sign all other requests.

For the initial exchange, X-MSS-API-USERKEY must be an empty string and is excluded from the HMAC canonical message. The canonical message is: [HTTP method][base URL without query params][timestamp] — no content-type (GET request) and no user key. See the signing guide for a worked example.

url="https://sandbox.api.portal.io/authenticate/apikeyexchange?UserName=user%40example.com&Password=MyP%40ss123"
base_url="https://sandbox.api.portal.io/authenticate/apikeyexchange"
timestamp="$(date -u '+%a, %d %b %Y %H:%M:%S GMT')"
canonical="GET${base_url}${timestamp}"
signature="$(printf '%s' "$canonical" | openssl dgst -sha256 -hmac 'YOUR_SECRET_KEY' -binary | base64)"

curl -i -X GET \
  "$url" \
  -H "Accept: application/json" \
  -H "X-MSS-API-APPID: YOUR_APP_ID" \
  -H "X-MSS-API-USERKEY: " \
  -H "X-MSS-CUSTOM-DATE: $timestamp" \
  -H "X-MSS-SIGNATURE: $signature"

import requests
from datetime import datetime, timezone
from email.utils import format_datetime
from portal_auth import sign_request  # See authentication guide

url = "https://sandbox.api.portal.io/authenticate/apikeyexchange?UserName=user%40example.com&Password=MyP%40ss123"
timestamp = format_datetime(datetime.now(timezone.utc), usegmt=True)
signature = sign_request("GET", url, "", timestamp, "", "YOUR_SECRET_KEY")

response = requests.get(url, headers={
    "Accept": "application/json",
    "X-MSS-API-APPID": "YOUR_APP_ID",
    "X-MSS-API-USERKEY": "",
    "X-MSS-CUSTOM-DATE": timestamp,
    "X-MSS-SIGNATURE": signature
})
print(response.json())

const { signRequest } = require('./portalAuth'); // See authentication guide

const url = "https://sandbox.api.portal.io/authenticate/apikeyexchange?UserName=user%40example.com&Password=MyP%40ss123";
const timestamp = new Date().toUTCString();
const signature = signRequest("GET", url, "", timestamp, "", "YOUR_SECRET_KEY");

const response = await fetch(url, {
    headers: {
        "Accept": "application/json",
        "X-MSS-API-APPID": "YOUR_APP_ID",
        "X-MSS-API-USERKEY": "",
        "X-MSS-CUSTOM-DATE": timestamp,
        "X-MSS-SIGNATURE": signature
    }
});
const data = await response.json();
console.log(data);

{
  "userId": "string",
  "sessionId": "string",
  "userName": "string",
  "displayName": "string",
  "bearerToken": "string",
  "refreshToken": "string",
  "refreshTokenExpiry": "2026-04-06T00:22:19Z",
  "profileUrl": "string",
  "roles": ["string"],
  "permissions": ["string"],
  "authProvider": "string",
  "meta": {
    "apiKey": "YOUR_USER_API_KEY"
  }
}

Authorizations

X-MSS-API-APPID

string

header

required

Portal application identifier used as part of HMAC-authenticated API requests.

X-MSS-API-USERKEY

string

header

required

Portal user API key used together with the HMAC signature headers.

X-MSS-CUSTOM-DATE

string

header

required

Timestamp header included in the signed request to prevent replay attacks.

X-MSS-SIGNATURE

string

header

required

HMAC-SHA256 signature for the request, calculated over the canonical string defined in the authentication docs.

Headers

string

required

Accept Header

Query Parameters

UserName

string

required

user email address

Maximum string length: 256

Password

string<password>

required

user password

Response

Success

AuthenticateResponse

userId

null | string

sessionId

null | string

userName

null | string

displayName

null | string

referrerUrl

null | string

bearerToken

null | string

refreshToken

null | string

refreshTokenExpiry

null | string<date-time>

profileUrl

null | string

roles

string[]

permissions

string[]

authProvider

null | string

Authentication

Proposals

Proposal Items

Change Orders

AI Builder

People

Catalog

Users

Webhooks

Zapier Triggers

Exchange Credentials for a User API Key

Authorizations

Headers

Query Parameters

Response