Authentication

HyoNova has two kinds of callers. People use the web app in a browser and authenticate with a session. Systems — your own servers — use the Mail API with an API key. This page explains both.

Members: signing in#

Members sign in at https://app.hyonova.com/sign-in with Work email and Password. New companies are created at https://app.hyonova.com/sign-up. People who are invited join from the invitation, either by setting a password or by signing in to an account they already have.

• Passwords need at least 8 characters and are stored only as a salted scrypt hash.
• Sign-in is rate limited more strictly than the rest of the product.
• An unknown email address goes through the same password check as a real one, so response time does not reveal which accounts exist.
• Forgot your password? on the sign-in page emails a reset link that works once, for 30 minutes.
• Each member manages their sign-in methods and changes their password in Settings under Sign-in & Security.

Browser sessions#

A successful sign-in creates a session on the server and sets a session cookie in the browser.

CSRF protection#

Every browser request that changes data — anything other than GET, HEAD or OPTIONS — must carry an anti-forgery token that belongs to the current session, in the X-CSRF-Token header. The web app receives this token with the session and sends it automatically. A request without the matching token is refused with 403 and the error code CSRF_DENIED.

Combined with SameSite=Strict cookies, this means another website cannot make changes in HyoNova on your behalf, even while you are signed in.

Guests: scoped links#

Guests do not have member accounts and do not receive a company session. A guest link works like a scoped, time-limited credential:

• It grants entry to one office world — or only to meetings — with exactly the abilities the host chose for the link. The server derives those abilities from the link on every request.
• It expires at the time chosen when it was created. Some links need the host's approval before the guest can enter.
• It is presented by the guest's browser explicitly with each guest request, never as an ambient cookie.
• Revoking the link, ending the visit or turning guest access off for the company ends the visit.

See Guest links.

Invitation links#

An invitation link lets one person join your company as a member. It is shown once when it is created, expires after 7 days, and can be revoked or replaced by a new link. See Invitations.

Systems: API keys for the Mail API#

Your servers call the Mail API with an API key, not a browser session.

• A Mail administrator creates keys in Mail › Automations › API keys. Each key has a name and one or more scopes, such as mail.transactional.send and mail.events.read.
• The secret is shown once. Keys start with hnm_, and HyoNova stores only a hash of each key.
• Send the key in the Authorization header: Authorization: Bearer YOUR_API_KEY. No cookies or CSRF tokens are involved.
• Revoke stops a key immediately. A revoked or unknown key gets 401 with API_KEY_INVALID; a key without the needed scope gets 403 with FORBIDDEN.
• Keep keys on your servers. Never ship one in a web page or a mobile app.

Webhooks work the other way round: HyoNova signs each request to your endpoint with a per-endpoint secret. See Webhooks.

Coming next#