Users and keys

Fromenance is a communication provenance platform, and access to a tenant is through user accounts with roles and through scoped API keys. This page covers both.

By the end you will have invited your team with the right roles and minted keys with the smallest scope that does the job.

Users

Settings, Users and roles, Invite. Or POST /v1/users with { "email": "...", "role": "analyst", "name": "..." }. The invitee gets a magic link; on first sign in they can register a passkey. Roles are described on Admin.

• Change a role with PATCH /v1/users/{id}; remove a user with DELETE /v1/users/{id}. Both need the admin or owner role and are audited.
• A tenant must keep at least one owner.
• The same person can belong to several tenants (for example a managed security provider). The tenant switcher in the top bar changes context; GET /v1/me lists memberships.
• Single sign on (SAML and OIDC) is planned for a later release.

API keys

Settings, API keys, Mint key. Or:

curl -X POST https://api.fromenance.com/v1/api-keys \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"statements-batch","mode":"live","scopes":["register"]}'

Property	Notes
Format	fr_live_ or fr_test_ followed by 40 hex characters. Only the first 12 characters (prefix) and a SHA-256 hash are stored; the secret is shown once
mode	live writes to production. test writes to a sandbox partition: registrations and submissions are marked sandbox: true and replies go to your fraud contact address, never to a customer
scopes	One or more of register, read, admin
last_used_at	Updated on use, visible in the list
Revoke	DELETE /v1/api-keys/{id}. Takes effect within a minute at the edge

Scopes map to endpoint groups:

Scope	Allows
register	POST /v1/communications, /batch, /reserve, PATCH /v1/communications/{id}
read	GET on communications, submissions, indicators, fraud list, stats, search, webhook delivery logs, and the tenant
admin	Everything an admin user can do: users, keys, domains, sources, templates, webhooks, overrides, fraud list writes, site keys, audit log

Give your sending system a register key and nothing else. Give your SIEM integration a read key. Reserve admin keys for provisioning scripts and rotate them when the script is done.

Use the key as a bearer token: Authorization: Bearer fr_live_.... Rate limits are per key: 600 requests per minute on register and reserve, 6,000 items per minute on batch.

The tenant secret

Recipient hashing uses a second secret, issued with your tenant and separate from every API key. The SDK takes it as tenantSecret; the curl examples take it as FROMENANCE_TENANT_SECRET. It never travels to the API. Store it with the same care as a live key, since anyone holding it can compute the recipient hash for an address. Ask your Fromenance contact if you need it re-issued; re-issuing invalidates the recipient hashes on every existing registration, so it is done with a re-registration plan.

Site keys

Site keys (sk_pub_...) authenticate the verify widget and are public by design; they are bound to allowed origins rather than kept secret. Verify page, New site key, or POST /v1/site-keys. Revoke with DELETE /v1/site-keys/{id}. Details on Verify page.

Sessions

The admin app uses a session cookie (fromenance.session_token) issued by magic link or passkey sign in. Sessions are bound to the browser and expire on sign out. API keys, not sessions, are the right credential for anything automated.