Mastodon Relay Inbox Authentication Errors: Fix

When you run a Mastodon relay, you may see inbox authentication errors in your server logs. These errors prevent the relay from properly forwarding public posts between instances. The root cause is almost always a mismatch in the relay’s authorization token or a misconfigured HTTPS connection. This article explains why these errors occur and provides step-by-step fixes to restore normal relay operation.

Why Mastodon Relay Inbox Authentication Errors Occur

A Mastodon relay acts as a central hub that redistributes public posts to all subscribed instances. When an instance sends a post to the relay’s inbox endpoint, the relay must verify that the request comes from an authorized source. This verification uses a shared access token. If the token is missing, expired, or mismatched, the relay rejects the delivery with an authentication error.

Another common cause is a broken HTTPS handshake. The relay’s server must present a valid TLS certificate that matches its domain name. If the certificate is self-signed, expired, or issued for a different domain, remote instances will refuse to connect. The error message in the relay logs typically reads HTTP 401 Unauthorized or SSL certificate verify failed.

A third cause is a firewall or reverse proxy that blocks or modifies the HTTPS traffic. For example, a proxy that strips the Authorization header will cause all inbox requests to fail authentication. Understanding these three root causes helps you pinpoint the exact fix needed.

Steps to Fix Mastodon Relay Inbox Authentication Errors

The following steps address the three most common causes. Perform them in order and test the relay after each step.

Step 1: Regenerate the Relay Access Token

1. Log in to your Mastodon relay administration interface
   Open a web browser and navigate to https://your-relay-domain/admin. Authenticate with your relay admin credentials.
2. Locate the access token settings
   Click Settings in the left sidebar. Scroll to the Relay Access Token section.
3. Generate a new token
   Click the Regenerate Token button. Copy the new token value that appears. The old token is immediately revoked.
4. Update all connected instances
   For each instance that subscribes to your relay, the admin must update the relay URL in their instance’s relay settings. The new URL format is https://your-relay-domain/inbox?access_token=NEW_TOKEN. Without this update, those instances will continue to send requests with the old token, causing authentication errors.

Step 2: Verify and Fix the HTTPS Certificate

1. Check the current certificate
   Run this command from any machine with network access to the relay: openssl s_client -connect your-relay-domain:443 -servername your-relay-domain. Look for the verify error lines in the output. A value of num=0 means the certificate is valid.
2. Obtain a valid TLS certificate
   If the certificate is expired or self-signed, install a free certificate from Let’s Encrypt using Certbot. On the relay server, run sudo certbot --nginx -d your-relay-domain and follow the prompts. Certbot automatically configures Nginx to use the new certificate.
3. Restart the web server
   After the certificate is installed, restart Nginx: sudo systemctl restart nginx. Verify the certificate again with the openssl command to confirm the error is gone.

Step 3: Configure Firewall and Reverse Proxy

1. Open port 443 in the firewall
   On the relay server, allow inbound HTTPS traffic: sudo ufw allow 443/tcp. If you use a different firewall tool, create a rule to permit TCP traffic on port 443.
2. Check reverse proxy headers
   If the relay sits behind Nginx as a reverse proxy, ensure the proxy passes the Authorization header. In the Nginx server block, add or confirm this line inside the location / block: proxy_set_header Authorization $http_authorization;.
3. Test the relay inbox endpoint
   From a remote machine, send a test POST request: curl -X POST -H "Authorization: Bearer YOUR_TOKEN" https://your-relay-domain/inbox. A 202 Accepted response means authentication is working. A 401 Unauthorized response indicates the token or certificate is still incorrect.

If Mastodon Relay Still Has Issues After the Main Fix

Relay Log Shows “Connection refused”

This error means the Mastodon relay service is not running. On the relay server, check the service status: sudo systemctl status mastodon-relay. If it is inactive, start it with sudo systemctl start mastodon-relay. Enable it to start on boot: sudo systemctl enable mastodon-relay.

Remote Instances Report “Invalid Token” After Token Regeneration

The new token may not have propagated to all connected instances. Contact each instance admin and ask them to update the relay URL. As a temporary workaround, you can set the old token back in the relay settings, but this leaves the relay vulnerable. Instead, send a mass notification to all instance admins with the new token and a deadline for the update.

Relay Works Locally but Fails from External Networks

This is usually a DNS or routing issue. Verify that the relay domain resolves to the correct public IP address from outside your network. Use a tool like whatsmydns.net to check global DNS propagation. If the IP is correct, check that your router forwards port 443 to the relay server’s internal IP.

Mastodon Relay Authentication: Token-Based vs Certificate-Based Verification

Item	Token-Based Verification	Certificate-Based Verification
Method	Shared secret string in the URL or header	TLS certificate presented during the HTTPS handshake
Error on failure	HTTP 401 Unauthorized	SSL certificate verify failed or connection reset
Rotation difficulty	Easy — regenerate token and update instances	Moderate — obtain new certificate and restart web server
Security level	Lower if token is transmitted in the URL	Higher — uses public-key cryptography
Common fix	Regenerate token and update relay URLs	Install a valid Let’s Encrypt certificate

You can now diagnose and fix Mastodon relay inbox authentication errors by regenerating the access token, installing a valid TLS certificate, and adjusting firewall or proxy settings. Test the relay after each change using a curl command to confirm the fix. As an advanced tip, monitor the relay logs in real time with sudo journalctl -u mastodon-relay -f to see authentication attempts as they happen.