Your end users sign in through a sign-in gate. The gate is a pool of end-user accounts together with everything that decides how those accounts sign in: the brand domains it is served on, its Google and GitHub providers, its sign-up policy and portal settings, its appearance, and the keys that sign its session tokens.
What belongs to a gate
| Part | What it means for you |
|---|---|
| End-user accounts | An email address is unique within a gate, without regard to letter case. Two gates never share an account, even for the same email address |
| Brand domains | The host names the hosted pages and the Public API are served on. The region finds the gate, and through it your application, from the host name of each request |
| Sign-in providers | Google and GitHub, enabled per gate; see Sign-in methods |
| Settings and appearance | The sign-up policy, the customer portal, the return and sign-in addresses, the display name, logo and primary colour; see Hosted pages, components or your own |
| Signing keys | Each gate signs its session tokens with keys of its own. A token signed by another gate is refused by your backend with issuer_mismatch |
Your own team signs in somewhere else. The operator console has a separate pool of accounts, and neither pool accepts the other's credentials.
One application or several
A gate has one of two shapes:
| Shape | Accounts | Settings |
|---|---|---|
| Dedicated to one application (the default) | The application's end users have accounts of their own. Someone who uses two of your applications holds two unrelated accounts | Apply to this application only |
| Shared by the applications of your organization | One account serves every application that shares the gate | Apply to every application that shares the gate; the console says so on the settings page |
An application is served by exactly one gate. With a shared gate, an email address registered under one of your brands can be discovered from another brand that shares it; keep gates dedicated when your applications must not reveal each other's users.
In ShipRev Cloud, every application you create gets a dedicated gate, and its operator console manages that application alone. The operator console shows the gate an application uses under Settings, Project, Identity Providers.
Brand domains
End users reach your gate on a domain of yours, for example account.example.com. You add the domain to the gate and prove that you control it with a DNS TXT record; Your brand domain has the steps, the record format and the usual causes of a failed verification.
What the region does with the host name of a request:
| The host name is | Sign-in and sign-up |
|---|---|
| A verified brand domain of your gate | Served, for your application |
| Registered but not yet verified | Refused with 403; nothing is created |
| Not registered with any gate | Refused with 404 |
A few rules follow from that:
- A domain can be registered once, for one gate. Adding it again, for any gate, is refused.
- A gate can have more than one brand domain; each is verified on its own.
- Google and GitHub return the end user to a brand domain, so each verified domain your end users sign in on needs its callback address registered with the provider.
- Invitation emails that point to the hosted pages use the gate's first verified brand domain. If you set a custom sign-in address, they point there instead.
- Calls to the Public API must arrive with your brand domain as their host name. From a browser, forward a path on your own origin, as in Forward a path on your own origin.
Removing a brand domain stops sign-in on that host name at once. Sessions that were already issued are not affected, because your backend verifies tokens against the gate's keys, not against the domain.