Account Authentication
Authentication using REST API
Credentials
You must use username and password for each request. For this case, it is required to set the API username and password:
Authorization header base64 encoded: e.g. "Basic d2lraTpwZWRpYQ==" (<username>:<password>)
While the API is exposed only over HTTPS, the credentials are encrypted.
IP Allowlist (optional)
During the Onboarding phase, you can configure an additional layer of security by using IP-Allowlist to allow REST JobRequests only from defined source IPs:
IP-Allowlist is optional.
By default, if no source IPs are defined, then there are no restrictions: all source IPs are allowed.
Credentials (see paragraph above) are still mandatory for each JobRequest.
Only IPv4 is supported.
All IPs have to be defined explicitly, we do not support IP-ranges (eg. 1.2.3.4/24).
Source IP is provided as HTTP Header X-Real-IP: 11.22.33.44.
If the header X-Real-IP: 11.22.33.44 is not present, requests will be rejected.
Retarus recommends configuring IP-allowlisting as a complementary authentication mechanism to increase security.
Authentication using SMTP Adatper
Credentials
You are able to use username and password for each request. For this case, it is required to set the API username and password. Those credentials must be base64 encoded. There are two different authentication mechanisms supported: Plain and Login.
Authentication by Source IP
As an alternative to using credentials (username and password), authentication can be done using Source IPs for SMTP JobRequest. In this case, an Authorization header is required:
If the mail sender uses SMTP AUTH, Basic Auth is used with the provided credentials. For authentication via sender IP address a custom form of the Authorization header is used:
Authorization: IPv4 <IP address in dotted notation>
Only IPv4 is supported
Authentication method using Credentials can still be used for the Account
Samples
Auth Plain
~> EHLO client.example.com
<~ 250-mail-de1.retarus.com
<~ 250-PIPELINING
<~ 250-SIZE 20000000
<~ 250-ETRN
<~ 250-AUTH PLAIN
<~ 250-AUTH=PLAIN
<~ 250-ENHANCEDSTATUSCODES
<~ 250-8BITMIME
<~ 250 DSN
~> AUTH PLAIN AHEhLXXXXZXIyAHpVcitRRRWw5XXX4
<~ 235 2.7.0 Authentication successful
Auth Login
~> EHLO client.example.com
<~ 250-mail-de.retarus.com
<~ 250-PIPELINING
<~ 250-SIZE 20000000
<~ 250-ETRN
<~ 250-AUTH PLAIN LOGIN
<~ 250-AUTH=PLAIN LOGIN
<~ 250-ENHANCEDSTATUSCODES
<~ 250-8BITMIME
<~ 250-DSN
<~ 250 CHUNKING
~> AUTH LOGIN
<~ 334 VXNlcm5hbWU6
~> eW91clVzZXJuYW1l
<~ 334 UGFzc3dvcmQ6
~> eW91clBhc3N3b3Jk
<~ 235 2.7.0 Authentication successful
~> AUTH LOGIN eW91clVzZXJuYW1l
<~ 334 UGFzc3dvcmQ6
~> eW91clBhc3N3b3Jk
<~ 235 2.7.0 Authentication successful