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

Headers

enum<string>

required

Accept Header

Available options:

application/json

X-MSS-API-APPID

string

required

Application Id

X-MSS-CUSTOM-DATE

string

required

A date timestamp of the request

X-MSS-SIGNATURE

string

required

A signature for the request

X-MSS-API-USERKEY

string

required

User API Key

Query Parameters

UserName

string

required

user email address

Maximum string length: 256

Password

string<password>

required

user password

Response

Success

AuthenticateResponse

userId

string

sessionId

string

userName

string

displayName

string

referrerUrl

string

bearerToken

string

refreshToken

string

refreshTokenExpiry

string<date-time>

profileUrl

string

roles

string[]

permissions

string[]

authProvider

string

responseStatus

ResponseStatus · object

ResponseStatus

Show child attributes

Authentication

Proposals

Change Orders

AI Builder

People

Catalog

Users

Webhooks

Zapier Triggers

Exchange Credentials for a User API Key

Headers

Query Parameters

Response