Exchange Credentials for a User API Key

GET /authenticate/apikeyexchange — Trade your Portal.io username and password for a User API Key required for all subsequent HMAC-authenticated requests.

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.

Request

GET /authenticate/apikeyexchange

Headers

Accept · string · required

Must be application/json.

X-MSS-API-APPID · string · required

Your API Application Key.

X-MSS-API-USERKEY · string · required

Send an empty string for the initial exchange. This value is also excluded from the HMAC canonical message during the initial exchange.

X-MSS-CUSTOM-DATE · string · required

Current UTC timestamp in RFC 7231 format, e.g. Mon, 06 Apr 2026 00:22:19 GMT.

X-MSS-SIGNATURE · string · required

HMAC-SHA256 signature of the canonical request message, Base64-encoded. See Signing requests for how to build the canonical message.

Query Parameters

UserName · string · required

The user’s Portal.io email address. Maximum 256 characters.

Password · string · required

The user’s Portal.io password.

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.

Response

200 Success

userId · string

Unique identifier of the authenticated user.

sessionId · string

Session identifier for this authentication session.

userName · string

The user’s email address / login name.

displayName · string

The user’s display name.

referrerUrl · string

The referring URL from the authentication context, when present.

bearerToken · string

A bearer token for session-based authentication. For the HMAC-based public API, use meta.apiKey instead.

refreshToken · string

Token that can be used to refresh the session.

refreshTokenExpiry · string

ISO 8601 expiry timestamp for the refresh token.

profileUrl · string

URL of the user’s profile.

roles · string[]

List of roles assigned to the user.

permissions · string[]

List of permissions granted to the user.

authProvider · string

Authentication provider used for this session.

responseStatus · object

Error status object, present when the request failed. Contains errorCode (string), message (string), stackTrace (string), and errors (array of error detail objects).

meta · object

Dictionary of string key-value pairs returned with the authentication response.

Show meta fields

meta.apiKey · string

The User API Key to use for all subsequent HMAC-authenticated requests. Pass this value in the X-MSS-API-USERKEY header and include it when building HMAC signatures.

Error Codes

Code	Meaning
401	Invalid credentials or the user’s email address has not been verified.

Example

curl

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"

200

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