Behind every option, the region runs the same identity service: accounts, password and social sign-in, invitations, password reset and session tokens. What you decide is who owns the sign-in page and whether your end users get a ready-made set of self-service pages. Both are settings of your application's sign-in gate, so you can change them later without touching the accounts.
The two choices
| Choice | Setting | Values |
|---|---|---|
| Do your end users get the customer portal? | Enable the customer portal | On (the default): after signing in they land in the portal, with subscription, billing, usage and members. Off: only the hosted identity pages are served, and end users are sent to your Default return address |
| Who owns the sign-in page? | Custom sign-in address | Empty (the default): the hosted sign-in page on your brand domain. Set: the address of your own sign-in page; invitation links point to it |
Both are under Settings, Project, Customer sign-in in the operator console, and only owners and admins can change them. Turning the portal off needs a default return address; the console refuses to save one without the other. Addresses must be full https addresses (plain http only on localhost), without a fragment, a wildcard or a user name.
The common combinations:
| Way | Portal | Custom sign-in address | End users see |
|---|---|---|---|
| Hosted sign-in, back to your app | Off, with your application's address as the default return address | Empty | The hosted sign-in page on your brand domain, then your application |
| Hosted sign-in and the customer portal | On | Empty | The hosted sign-in page, then the portal |
| Your own sign-in page | On or off, depending on whether you also want the portal | Your page's address | Your own pages, built with the React components or the Public API |
To choose, ask in order: must the sign-in page be part of your product, and will your team maintain it? Then use your own page. Otherwise, does your application already show subscription and usage itself? Then send end users back to your app; if not, give them the portal.
What the hosted pages cover
The hosted pages are served on your verified brand domain, with your gate's display name, logo and primary colour:
- Sign-in and sign-up, with Google and GitHub when you have enabled them.
- Accepting an invitation, and signing up from one.
- Password reset.
- The customer portal, when it is on.
The appearance is set in the same place, under Brand appearance, and applies to every hosted page. Custom styles, scripts and per-domain appearances are not offered.
Where each flow ends
| The end user | Ends at |
|---|---|
| Opens the hosted sign-in or sign-up page and completes it | Portal on: the portal. Portal off: your default return address. Portal off with a custom sign-in address: the hosted page sends them to your page instead of showing its form |
| Accepts an invitation on the hosted page, or signs up from it | The portal, or your default return address when the portal is off |
| Resets their password | No session is issued. The confirmation offers Sign in, which leads to your own sign-in page when the portal is off and a custom sign-in address is set, and to the hosted sign-in page otherwise |
| Signs in on your own page | Wherever your page sends them; your page receives the session |
Sending an end user to your default return address carries no token and no query parameter: the session stays with the hosted pages on your brand domain. A sign-in on your own pages, with the React components or the Public API, is what hands a session to your application.
With the portal off, its self-service pages redirect to your default return address and the hosted identity pages show no links to them. The Public API keeps serving subscriptions, plans, usage and organizations, so the React components inside your application keep working.
Your own sign-in page
Build it with the React components or call the Public API directly. Either way, three things are yours to handle:
- Forwarding. The components call a path on your own origin, which your server forwards to your brand domain. Forward a path on your own origin has the forwarding rule and examples.
- Holding the session. The components store nothing.
SignInFormandSignUpFormhand you the issued session once the end user's email address is confirmed, and you return the access token on every request; seegetAccessTokenandonUnauthorized. Which published version includes the confirmation step is in Sign-in methods. - Invitations. With a custom sign-in address set, invitation emails link to it with an
invitation_tokenquery parameter. Read it, show the invitation withGET /public/v1/invitations/info, then either accept it for a signed-in end user or sign the new end user up with it; Buyer organizations describes both.
Social sign-in and password reset stay on the hosted pages. Link to them from your page if your end users need them.
Next
- The React components: install them and wire the provider.
- Sessions and tokens: what your backend receives with every request.
- Gates and brand domains: the domain the hosted pages are served on.