Skip to main content
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.
​
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.
​
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

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

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

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