Skip to main content
Every Portal.io API request must be signed using HMAC-SHA256. Authentication works in two stages: first you exchange your Portal.io username and password for a User API Key, then you include that User Key in the signature of all subsequent requests. There are no session cookies and no OAuth flows — each request is independently authenticated by its signature headers.

​
How authentication works

Step 1 — Exchange credentials for a User Key. Call GET /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:

​
Obtaining credentials

To get your API Application Key and Secret Key:
  1. Create a free sandbox account at https://sandbox.portal.io and verify your email address.
  2. Contact your Portal.io representative. Let them know you have a sandbox account, and they will provide both keys.
Your User API Key is obtained programmatically by calling the GET /authenticate/apikeyexchange endpoint with your Portal.io username and password. See the quickstart for a full walkthrough with curl examples.

​
Common errors

For a detailed explanation of how to construct the HMAC signature, see Signing requests.