Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 8.2

How the node decides whether to let an HTTP request in

critical

API key and access level
Two ways to identify yourself, and the second is stronger

The node has three HTTP interfaces — the configuration files API (§ 8.2), the configuration API (§ 8.3) and the command API (§ 8.4) — and all three answer on one port together with the web monitor. They share an admission rule, and it consists of two halves.

The first half is the access level by address. It comes from http-access: monitor reads the state, operator additionally reads the configuration and runs commands, admin also edits the configuration.

The second half is the key http-api-key in the X-API-Key header. The manual states its power three times and identically: a valid key overrides the address restriction, and the request is accepted from any address.

Hence a simple rule. For reading you do not need to give out a key — the operator level from an allowed address is enough. For changes a key is always required: writing a configuration file, editing lists and sending addresses, submitting a command.

A request that passes neither half gets a 403. And the response is talkative: the body of the refusal names the configuration file path, the monitor log path and a ready-made http-access <address> admin line — verified on a fleet node.

The main trap is treating the two halves as layers of protection. They do not add up: the key is not added to the address restriction, it replaces it. A node closed with a narrow address list and equipped with a key is open to the whole world for whoever has that key.
What the Hub does. It uses both halves as intended: it gives its own address monitor — reading telemetry is enough — and sends commands with the key. This way the admin level does not go to all the machines behind a shared network exit.

🔴 Our weak spot is not the scheme but the channel: the key goes to the node over plain http://, because the template has http-redirect-to-https set to false. The stronger half — and it is exactly that half that travels in the clear.

Recommended values

The mechanism has no values of its own: two directives set them.

What is needed How it is achieved Default
reading the state http-access at the monitor level none, that is, closed
reading the configuration, commands the operator level closed
editing the configuration http-api-key in the header no keys

Different applications get different keys: revoking one does not break the others.

The admission rule, the key overriding the address restriction and the key being required for changes come from the manual (§ 8.2, § 8.3, § 8.4). That the refusal body reveals paths and a ready-made line is our own check on a fleet node.
Example configuration
# reading — by address, changes — by key
http-mgmt-port 1000
http-access 127.0.0.1 admin
http-access 10.0.0.5 monitor
http-api-key abcd_0123_abcd_0123_abcd_0123_ab
Reading is enough for the Hub’s address: it performs administrative actions with the key. This way the admin level is not given to every machine behind the same network exit.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends3 mistakes▶

Treating the key as a second factor on top of the address list

§ 8.2

What it costsThe halves do not add up. The key overrides the list rather than supplementing it, and the node is open from anywhere to whoever has the key.
How to spot itThe access list is narrow, yet the monitor log shows successful requests from outside.
How to do it rightTreat the key as equal to full access to the node and protect it accordingly.

Handing out a key just for reading

§ 8.3

What it costsThe access level by address is enough to read the state and the configuration. A key issued for exporting reports also grants the right to rewrite the configuration and run any command.
How to spot itAn application that only reads has a key.
How to do it rightGive the address operator and do without a key.

Transmitting the key over an unencrypted connection

our experience

What it costsThe strong half of the mechanism goes over the wire in plain text. Whoever intercepts it gets full access to the node from any address.
How to spot itThe configuration has http-redirect-to-https set to false, and the client sends X-API-Key.
How to do it rightEnable the redirect to https and teach the client to trust the monitor’s certificate.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Inheritance
The mechanism has no inheritance — the directives that enable it are inherited, and both are written at the root of the file, in the Global section. There is no split by interface whatsoever: one address list and one set of keys serve both the monitor and all three APIs.
⇄

Related entries

3 relations

Does not work without

http-api-keyGlobalThe key is the second way to identify yourself, and it is stronger than the first. § 8.2

Depends on

What protects the web monitor and what that protection is notThe three HTTP interfaces have the same admission rule as the monitor itself: they answer on one port. § 8.2http-accessGlobalThe access level by address is the first way to identify yourself, and the key overrides it. § 8.2

Referenced from

Run a command over the networkThe mechanism that is visible here. § 8.4

How to check on the node
Check both halves in turn. First, the address without a key:
curl -s -o /dev/null -w '%{http_code}\n' http://NODE:1000/status
403 means the address is not allowed. Now the same request with the header -H ‘X-API-Key: KEY’: a 200 response confirms that the key overrides the address restriction — that is, the mechanism works as described.
◇

What else to read

3 articles

◇What protects the web monitor and what that protection is notThree different protections — an address list, encryption and advice not to expose the monitor to the internet; there is not a single account.◇The activation key is a prerequisite for installation, not a step after itWithout an activation key from SparkPost support the engine neither installs nor runs, and the license tier sets the outbound connection ceiling: on Standard everything above 200 is ignored.◇Cloud restrictionsClouds restrict outbound mail on port 25 until you ask them to lift the limit, and mailbox providers treat their address ranges with suspicion.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Prepare a node for sending · Node security
Priority
critical