Network and key safety

The API is only as safe as the key and the network path to it.

HTTPS only#

Call the API over HTTPS. A key sent over plain HTTP should be treated as leaked: ask the administrator to rotate it.

Keeping a key safe#

• Keep the key in a secret store or your platform's encrypted configuration, never in source control.
• Never put it in a URL, a log line, a ticket, an email or a chat message. When you discuss a key, use its prefix (the first 16 characters).
• Give each integration its own key, with only the scopes and institutions it needs. Revoking one integration then leaves the others working.
• If a key may have leaked, ask the administrator to rotate it. The old secret stops working on the next request.

IP allowlists#

The administrator can restrict a key to a list of IPv4 or IPv6 addresses or CIDR ranges. A request from any other address is 403 ip_not_allowed.

• Tell the administrator which address your system sends from, and tell them before it changes.

Systems inside your own network#

When MASK runs on your servers or inside your internal network (see Deployment options), the API is reachable only where your network allows it, and your integration talks to it directly. The keys, scopes and allowlists work the same way.