# nine fish > One identity, every domain you own. Email forwarding and single sign-on at each domain a small company owns: hello@, support@ and each person's own name forwarded to the mailbox they already use, and sign-in to the platforms they use for each brand with an identity on that brand's domain, over OpenID Connect or SAML at auth.. Run from the `nf` CLI and an HTTP API, billed by use in Australian dollars, with no seats or subscription. It is for a company of one to three people running several brands, each on its own domain. Use the service's own words: organisation, person, domain, forward, platform. - An organisation is the company. It has one owner, who alone handles billing, hands the organisation on and closes it; everyone else is a member, who can do everything else. - A domain is set up once, with `nf domain setup`: its forwards, its sign-in host (auth. by default) and the person's own name, then every DNS record at once. - A forward sends an address at a domain to a mailbox, or to another of the organisation's addresses (support@ to alex@), following wherever that one forwards. The mailbox it goes to, not the address at the domain, agrees first: the first time a mailbox is used it is emailed a link, and mail goes to it once that link is clicked. - A platform is one the company signs in to, on one of its domains. Its issuer is the domain's sign-in host, such as https://auth.example.com, and it sees each person as their name at that domain. Where a platform only wants an email address, the forwarded address is the login. - The people who sign in see the brand's own pages at auth., never this service's name. ## Using the nf CLI - The CLI is `nf`. It isn't publicly distributed yet, so don't suggest an install command. Start with `nf login`, which signs in with a passkey in the browser (`nf login --device` where there is no browser, and for scripts and CI, which run as the person who signed them in). - Use `--profile prod` (or `NF_PROFILE=prod`): with nothing selected, nf uses the dev stage. - Commands inside an organisation take `--org `, or `NF_ORG`, or the profile's organisation (`nf org use `). - At a terminal, `nf domain setup` and `nf platform add` ask for what is left out. Every question has a flag, and under `--json` or `--no-interactive` nf never asks. - Add `--json` (or `-o json`) for machine-readable output. Errors in JSON are `{code, message, request_id, details, retryable}`. Rely on exit codes rather than parsing text. - Reading (`list`, `show`) changes nothing and is safe to run. Each change is one command and safe to retry. Adding a card, a callback or a mailbox, changing a secret or ownership, or giving a member a name needs a passkey from the last five minutes: at a terminal nf opens the browser for it and carries on; elsewhere it exits 6. Ask the user first and tell them the exact command. - `nf help ` lists a command's options. Exit codes: - 0: it worked - 1: something else failed - 2: the command line is wrong, or the API refused a value - 3: not signed in, or the session expired: run `nf login` - 4: not found, or not visible to you - 5: conflict: it changed since it was read - 6: it needs a passkey from the last five minutes (a step-up) - 7: the config, profile or stage is missing or invalid - 8: signed in, but not allowed - 9: timeout, rate limit or server error: retrying may work ## Get started Examples use the organisation `acme`, the domain `example.com` and the mailbox `me@example.net`. Output is abridged. ### Your organisation Sign in with a passkey, make an organisation and add a card. - Nothing active, nothing to pay - Invite a second person to run domains, forwards and platforms - Billing stays with you ```sh nf login nf org create acme nf billing setup nf person invite sam@example.com ``` ### Set up a domain Setup asks three questions, then prints every DNS record the domain needs at once. - Which addresses forward, and where - Its sign-in host - Your own name at the domain ```sh nf domain setup example.com ``` ### Check the records Publish the records, then run check. - Each part turns on as its record appears - A new mailbox is emailed a link, and mail goes to it once it’s clicked - Do the same for each brand ```sh nf domain check example.com ``` ### Forward mail Forward any address in one command. There are no mailboxes to run. - To the mailbox you already use, such as me@example.net - Or to another of your addresses, such as alex@example.com - A new mailbox agrees first, by a link in an email ```sh nf email route create support@example.com --to alex@example.com nf email route create security@example.com --to sam@example.net ``` ### Sign in to your platforms Add a platform, then paste what nf prints into its single sign-on settings. - Everyone signs in with their passkey, as their name at your domain - OpenID Connect by default, or SAML with --saml - No single sign-on setting? Sign up with your forwarded address ```sh nf platform add nf platform add --saml ``` ### Brand your sign-in pages People sign in on your own host, such as auth.example.com, with your name, logo and colours. - Set it once for the organisation - Give one domain its own look with --domain - Light and dark: add dark colours and a dark logo, and pages follow each person's setting ```sh nf org branding set --name Acme \ --primary '#0b6e4f' --background '#ffffff' \ --logo ./acme.png nf org branding set --name 'Acme Studio' --domain example.com \ --primary '#1f4fd8' --background '#ffffff' ``` ## Next steps ### Connect a platform In the platform’s settings, find single sign-on (often called SSO, OpenID Connect or OIDC). It gives you a callback address; platform add asks for it and prints what to paste back. Adding a callback needs a passkey from the last five minutes: if yours is older, nf opens the browser to ask for it, then carries on. ```sh $ nf platform add Name for this platform? helpdesk Which domain? [example.com] Callback address the platform gave you? https://helpdesk.example.org/sso/callback Added helpdesk on example.com. Every member can sign in to it. Paste these into the platform: Issuer https://auth.example.com Client ID plt_… Client secret … Callback https://helpdesk.example.org/sso/callback This secret is shown once and won't be shown again. To replace it: nf platform rotate-secret helpdesk. ``` The issuer is the domain’s own sign-in host, so the platform only ever sees addresses on your domain. Everyone in the organisation can sign in to it with their passkey, on your brand’s pages at auth.example.com, and the platform sees each of them as their name at example.com, such as alex@example.com. Nobody else can sign in. platform show prints the same values again, without the secret. For a platform that offers only SAML, add --saml. It asks for the entity ID and the ACS (reply) address the platform gives you, and prints the values to paste back, with the certificate under them: ```sh $ nf platform add --saml Name for this platform? wiki Which domain? [example.com] Entity ID the platform gave you? https://wiki.example.org/saml ACS (reply) address the platform gave you? https://wiki.example.org/saml/acs IdP entity ID https://auth.example.com/saml/plt_…/metadata Metadata URL https://auth.example.com/saml/plt_…/metadata SSO URL https://auth.example.com/saml/plt_…/sso NameID @example.com (emailAddress) Certificate (PEM, below) ``` Some platforms have no single sign-on setting and only want an email address. Sign up with your forwarded address, such as alex@example.com or support@example.com: its mail, including sign-in links and password resets, reaches your mailbox. ### Invite a person An invite emails a link; they sign up with a passkey and join as a member. An address on one of your domains gives them that name, so platforms see sam@example.com as sam at each of your domains; --name gives another. ```sh $ nf person invite sam@example.com $ nf person list ``` A member can do everything with domains, forwards and platforms, and invite people. Only the owner handles billing, hands the organisation to someone else, and closes it. Removing a person stops their sign-in at every platform at once. ```sh $ nf person remove mem_… ``` ### Brand the sign-in page People sign in on your domain’s own host, with your name, logo and colours and nothing of ours. Set the organisation’s brand once; a domain with no brand of its own shows it. With --domain, a domain gets its own, for a brand that looks different. ```sh $ nf org branding set --name Acme --primary '#0b6e4f' --background '#ffffff' $ nf org branding set --domain example.com --name 'Acme Studio' --primary '#1f4fd8' --background '#ffffff' --logo ./studio.png ``` The primary colour needs at least 3:1 contrast against the background, and a logo is a PNG of at most 256 KiB. For people whose system is in dark mode, add dark colours and a dark logo; the pages follow each person's setting. Without them, the one palette and logo show in both modes. --light-only drops the dark colours. ```sh $ nf org branding set --name Acme --primary '#0b6e4f' --background '#ffffff' --dark-primary '#6fd3a8' --dark-background '#0f1712' --dark-logo ./acme-dark.png ``` ### Scripts Every command takes --json, and every change is safe to retry. Every question nf asks has a flag, and under --json or --no-interactive nf never asks: ```sh $ nf domain setup example.com --email yes --routes hello=me@example.net,alex=me@example.net --host auth.example.com --name alex --json $ nf platform add helpdesk --domain example.com --callback https://helpdesk.example.org/sso/callback --secret-file ./helpdesk.secret --json $ nf platform add wiki --saml --domain example.com --entity-id https://wiki.example.org/saml --acs https://wiki.example.org/saml/acs --json ``` A client secret never goes to JSON: --secret-file writes it to a file only you can read. A script or CI job runs as you: sign it in once where it runs, and approve the code from any browser. It can do what you can, nothing more. A change that needs a fresh passkey exits 6 there instead of opening a browser. ```sh $ nf login --device ``` ### The API Everything nf does is a call to the HTTP API, with the same sign-in and the same rules. Its OpenAPI document describes every operation. The OpenAPI document: https://nine.fish/openapi/v1.json ## Pricing Rates, in AUD: - Active domain: A$0.0006 / hour · A$0.438 / month - Active platform: A$0.001 / hour · A$0.73 / month - Completed sign-in: A$0.005 - Forwarded email, per accepted recipient: A$0.0005 An organisation with nothing active is free: people, pending domains, the CLI and the API cost nothing. A pending domain claim expires after 7 days. Usage is invoiced once it reaches A$10, and at least once a year. Two domains forwarding mail and one platform, active for a 730-hour month: 2 × A$0.44 + A$0.73 = A$1.61. With 200 forwarded emails and 20 sign-ins that month, it is A$1.81. ## Links - [Home](https://nine.fish/): getting started and pricing - [OpenAPI document](https://nine.fish/openapi/v1.json) - [Terms of service](https://nine.fish/terms) - [Privacy policy](https://nine.fish/privacy) - [Support](mailto:support@nine.fish): support@nine.fish Operated by 9F PTY LTD (ABN 83 679 546 064), Australia.