Exchange Credentials for a User API Key

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

import requests
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 = "Mon, 06 Apr 2026 00:22:19 GMT"
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

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

import requests
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 = "Mon, 06 Apr 2026 00:22:19 GMT"
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.

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

import requests
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 = "Mon, 06 Apr 2026 00:22:19 GMT"
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

enum<string>

required

Accept Header

Available options:

application/json

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

responseStatus

ResponseStatus · object

ResponseStatus

Show child attributes

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