How authentication works
Step 1 — Exchange credentials for a User Key. CallGET /authenticate/apikeyexchange with your username and password as query parameters. For this request only, the X-MSS-API-USERKEY header is an empty string and is excluded from the HMAC canonical message. A successful response returns a User API Key at meta.apiKey in the response body.
Step 2 — Sign all subsequent requests with the User Key.
Include your User Key in the X-MSS-API-USERKEY header and incorporate it into the HMAC canonical message for every request you make after the initial exchange.
See Signing requests for the full details on building the canonical message and computing the signature.
Required headers
Every request to the Portal.io API must include the following headers:| Header | Description | Example |
|---|---|---|
Accept | Must be application/json | application/json |
X-MSS-API-APPID | Your API Application Key, provided by your Portal.io representative | D78C5B43-60B7-4F06-9372-0B3F9010D042 |
X-MSS-API-USERKEY | The User API Key obtained from the credential exchange. Use an empty string for the initial exchange request. | qBOSOYDeZaSzTxqMCL1Kr66JpU2H6wHCLz7xviZUOcA= |
X-MSS-CUSTOM-DATE | Current UTC date and time in RFC 7231 format. Must exactly match the timestamp used in your HMAC signature. | Mon, 06 Apr 2026 00:22:19 GMT |
X-MSS-SIGNATURE | HMAC-SHA256 of the canonical message, Base64 encoded | 3Tsd9... |
Obtaining credentials
To get your API Application Key and Secret Key:- Create a free sandbox account at https://sandbox.portal.io and verify your email address.
- Contact your Portal.io representative. Let them know you have a sandbox account, and they will provide both keys.
GET /authenticate/apikeyexchange endpoint with your Portal.io username and password. See the quickstart for a full walkthrough with curl examples.
Common errors
| Status | Cause | Fix |
|---|---|---|
401 | Invalid credentials or unverified email address | Confirm your username and password are correct. Check that you verified your email after signing up. |
401 | Signature mismatch (body: "You are not authorized. Your request signature (hash) is invalid.") | Ensure the canonical message is assembled in the correct order (see Signing requests), that you are using the base URL without query parameters, that your timestamp in X-MSS-CUSTOM-DATE exactly matches the value in the canonical message, and that you are using the Secret Key as raw ASCII bytes without Base64-decoding it first. For POST requests, confirm the Content-Type is included in the canonical message. |
403 | Insufficient permissions | The authenticated user does not have permission for the requested resource or action. |