Skip to main content

Authentication

Hermes uses an API key in the X-API-Key request header:

X-API-Key: <read-from-your-secret-manager>

Do not send the key in the query string. The public API has no anonymous access, public signup, or self-service key creation.

Credential scope​

Hermes manually issues a public credential for one approved organization, customer, environment, and capability. The request cannot select or override that customer. Test and production credentials are separate; a credential issued for one environment is not valid in another.

Only credentials authorized for public EML analysis can use this operation. Internal, legacy, Gmail, Outlook, and other channel credentials are outside this public contract. A public API credential cannot be used as a shortcut into legacy routes.

Obtain a key​

Contact info@phishinghermes.com. Hermes operations confirms the intended customer and environment before issuing access. The portal never asks for, stores, or tests a key.

Store it​

  • Keep the key in a secrets manager or protected backend environment variable.
  • Never put it in Git, browser JavaScript, mobile binaries, .eml fixtures, logs, screenshots, analytics, tickets, or URLs.
  • Redact the complete X-API-Key header at every observability boundary.
  • Do not send a production credential to development or test infrastructure.

Rotate or revoke it​

Contact Hermes operations to replace or revoke a credential. Design the backend so a replacement can be deployed before the old credential is revoked. Public v1 contains no key-management endpoint.

Authentication and authorization errors​

  • 401 invalid_credentials is deliberately generic for a credential that cannot authenticate. Do not use it to infer whether a key exists, expired, or was revoked.
  • 403 means an authenticated credential is not authorized for this operation in its assigned scope. Do not retry without a corrected authorization or credential.
Server-to-server only

A browser or mobile application cannot keep an API key secret. Call Hermes from a controlled backend. The static API Reference has interactive authentication and request execution disabled.