Demo
Demo

Knowledge base

PMTA knowledge base›Block <transmissions-api>›Directive§ 3.3.20.1

api-key

<transmissions-api>

Keys that grant the right to use the Transmissions API
in the configuration this is a lineapi-keyinside the block <transmissions-api>
The same name 2:<inline-seeding><signals><transmissions-api>— some of them are other settings, some are the same one
A pass for submission over HTTP

The line sets a key for applications that submit mail through the Transmissions API. The application passes it in the Authorization header, and with a valid key gets the right to use this entry point.

The directive is repeated — any number of times, one line per key. This is the way to give different keys to different applications and revoke one without touching the others.

The manual sets a strict requirement for the value: letters, digits and underscore, from 32 to 128 characters long.

The key sits in the configuration in plain text — like submission passwords. So the file has to be protected accordingly.

The main trap is one key for everyone. The ability to create several keys exists precisely for revocation: an application that is no longer trusted loses access when one line is removed. With a single key, revocation means changing the key for everyone at once — that is, stopping all API submission.

It is the same story as with login passwords, and the cost of the mistake is the same: separation that exists only on paper.

What the Hub does. It does not write it: there is no Transmissions API block in its configuration at all — submission goes over regular SMTP under a login.

The key the Hub does write out is a different one: http-api-key for the web monitor and the management HTTP API. They are easy to confuse by name, but they are different entry points with different rights.

Recommended values

What to set. The value is the key itself; the rules come from the manual’s requirement and from common sense:

Property Why
32–128 characters, letters, digits, underscore the engine’s requirement: it will not accept anything shorter or with other characters
random the key is passed in a header and sits in the file in the clear
one per application otherwise revoking one access stops them all

The block should have as many lines as there are submitting applications — this is not redundancy but the only way to revoke.

The Authorization header, the repeatability of the directive and the value requirements come from the manual, § 3.3.20.1. The advice about a key per application is ours, for the same reasons as with login passwords.
Example configuration
# a key per application — otherwise revoking one stops them all
<transmissions-api>
    api-key 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf    api-key 476d2e5b1d2bad079bf14ac5499cfdd2bb2859e4
</transmissions-api>
Removing one line revokes access for one application. The others keep working, and nothing needs to change for them.
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▶

Creating one key for all applications

§ 3.3.20.1

What it costsAccess cannot be revoked for one application: changing the key stops submission for all of them at once. The ability to repeat the directive exists precisely for this.
How to spot itThe block has one key line, while there are several submitting applications.
How to do it rightCreate a key per application and hand them out separately.

Choosing a short or “readable” key

§ 3.3.20.1

What it costsThe engine will not accept a value shorter than 32 characters or with characters other than letters, digits and underscore. And an accepted but meaningful key is a password that can be guessed.
How to spot itThe engine rejects the configuration, or the key looks like a word.
How to do it rightGenerate a random string of the required length rather than making one up.

Confusing this key with the management key

our experience

What it costsThese are different entry points: one grants the right to submit mail, the other to manage the node. A key put in the wrong block does not work, and one put in both grants more rights than intended.
How to spot itThe submission application gets a refusal, even though the key is “configured.”
How to do it rightLook at which block the line is in: submission is in the Transmissions API block, management at the root of the file.
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.
Reference data
Syntax
api-key <string>
Values
a string of letters, digits and underscores from 32 to 128 characters long
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<transmissions-api>
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <transmissions-api> and applies to the whole entry point: there is one block per node, and it has no inheritance. Separation between applications is achieved not by scope but by the number of keys.
⇄

Related directives

2 relations

Does not work without

Lock down permissions on configuration filesThe key sits in plain text, and permissions on the file are what protect it. § 3.3.20.1

Same name in other blocks

http-api-keyGlobalThe key for a different entry point — the web monitor and the management HTTP API; the names are similar, the rights are different. § 3.3.20.1

Referenced from

tls-certificate<transmissions-api-listener>Encryption proves who the listener is; the key proves who the client is. The API entry point requires both. § 8.1

How to check on the node
The keys are visible in the configuration; it is also worth checking the permissions on the file:
grep -c '^ *api-key ' /etc/pmta/config
ls -l /etc/pmta/config
The first command shows how many keys have been created; one with several submitting applications means access cannot be revoked for just one. The second shows that the file with the keys is closed to outsiders.
◇

What else to read

3 articles

◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.◇Who is allowed to submit mail and for whom to accept itOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.◇Headers the sender uses to control deliverySix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connect a sending platform
Neighboring settings of the block <transmissions-api>:max-message-sizelog-datalog-requestslog-tlsAll 5 directives of the block →