Security

Block-Auth proves who the user is. Keeping that proof safe in your app depends on a few rules. Follow them and your integration can't be spoofed from the browser.

Your keys

Key	Where it goes	Why
`apiKey`	Frontend and backend.	It's public: it only says which app is calling.
`apiSecret`	Only your backend, in an environment variable or a secret manager.	It proves the request comes from your server.

The API never receives the apiSecret itself: you send its SHA-256 hash. Treat the hash as secret too. It's what the API accepts, and the key that signs your webhooks.
Keep the secret out of your code, your repository, your logs and your error reports.
Use one app per environment. A secret from development or staging then never opens production.

If your secret leaks

The Dashboard can't rotate the apiSecret by itself yet. If you think it has leaked:

Contact Block-Auth support right away, with your API key and never the secret itself.
Remove it from wherever it was exposed (repository, logs, a shared file) and check who had access.
Review recent activity with /api/logs for logins you don't recognize.

Always check state

In the redirect login, your backend sends a state and gets it back with the code. Check it before redeeming the code.

Generate a new random value for each login and keep it in the user's session.
On the callback, compare it with the state you receive. If it doesn't match or is missing, stop.
Without this check, an attacker can make a victim's browser finish a login the attacker started, and the victim ends up signed in as the attacker.

The widget does the equivalent for you with PKCE: you don't need a state there.

How long a session lasts

/api/auth/token returns signedExpiredAt: the moment the user's signature for your app expires. Each user chooses that duration in Identity, within the limits your app sets in the Dashboard. It's 1 hour by default, between 30 seconds and 24 hours.

Don't let your session outlive signedExpiredAt. When it passes, ask the user to log in again.
End the session when you get the signout webhook.
When the user logs out of your app, also call /api/auth/signout, so the session closes on their other devices too.

Backend only

The apiSecret and its hash.
The access tokens from /api/signin: the data API is for your backend only.
The decision about who the user is. Your backend creates its session only from the address it gets from /api/auth/token, never from an address the browser sends.

Your own session cookie should be HttpOnly, Secure and SameSite=Lax, and your site should run on https.