Customer portal and teams
Customers manage devices, team members, seats, plans and invoices themselves: how invitations, member license keys, paused members and sign in work in Keygate.
Every Keygate install comes with a customer portal at BASE_URL/portal. Customers use it to find their keys, manage their devices and team, and handle billing without writing to you. It carries your site name and logo, and it is translated into English and Chinese.
Signing in
Customers sign in with the email address their license was issued to. Keygate emails them a six digit code that is valid for ten minutes, so there are no passwords to reset. Link to the portal from your app's help menu and from your website so people can find it when they need it.
Each code can be tried five times; after the fifth wrong guess the customer has to request a new one. An address can request three codes every ten minutes; a fourth request is refused for up to ten minutes.
What customers can do
| Task | Where in the portal |
|---|---|
| See their licenses, keys, plans and end dates. | My Licenses |
| Free a device they no longer use, such as a lost or replaced laptop. | Devices on the license |
| Invite and remove team members, and resend or cancel invitations. | Members on the license |
| Change how many seats a per-seat subscription pays for. | Change seats, or Add seats under Members |
| Switch a subscription to another subscription plan of the same product, for example from monthly to yearly. | Change Plan |
| Move a license on a free plan to a paid plan and keep its key. They pay on Stripe Checkout and the same license moves to the new plan. | Upgrade |
| Cancel a subscription at the end of the period, or at once. | Cancel Subscription |
| Download invoices, and update the card on a Stripe subscription. | View Invoices, Update Payment |
| Extend the update period of a perpetual license. | Renew updates |
The billing actions appear only for licenses paid through Stripe, and only to the owner of the license, not to team members. Change seats appears on per-seat subscriptions whose plan sells more than one number of seats. Upgrade appears on free licenses that can be upgraded. See Selling with Stripe for what happens behind each of them, and upgrading a free license for when the button shows.
Changing plans and seats
This section covers how Change Plan and Change seats bill a Stripe subscription. Both work the same way: the owner picks the new plan or number of seats, sees the price Stripe calculates, including tax, discounts and any account credit, and then confirms. Nothing changes before they confirm, and a price shown more than an hour ago has to be reviewed again.
| The change | How it is billed |
|---|---|
| Costs more and lowers no limit, such as more seats or a dearer plan. | Stripe invoices the difference for the rest of the billing period at once, and the change applies as soon as that payment goes through. If the card is declined or the bank wants the customer to confirm, the change waits for payment: the portal offers Pay now, and Stripe drops the change if it is not paid by the date shown, with nothing charged. |
| Costs less and lowers no limit. | The change applies at once, and the difference for the rest of the period goes to the customer's account balance, used on future invoices. |
| Lowers a limit, such as fewer seats, or a plan with fewer devices or people. | A downgrade. It applies at once and is not prorated: the rest of the period is not refunded, and the next invoice bills the new terms. |
| Lowers one limit while raising another, or lowers a limit but costs more or bills on another interval. | Cannot be made in the portal. The customer is asked to contact you. |
- A change that would leave fewer seats than the people on or invited to the license, counting the owner, or fewer devices than are in use, is refused. Nobody and nothing is removed by a change: the customer removes members, cancels invitations or frees devices first.
- Moving to a per-seat plan, the owner chooses the seats first. The choice starts at the seats the license has now, and at least a seat for everyone on it, within the plan's range.
- A change waiting for payment is shown on the license, and the owner can cancel it. Making another change replaces it.
- The license follows the subscription as Stripe reports it. When its plan or seats move, Keygate sends the
plan.changedorlicense.quantity_changedwebhook.
Licenses not billed by Stripe have no Change Plan or Change seats in the portal: an admin changes them in the dashboard. See changing plans and per-seat pricing.
Teams and seats
Seats are for SaaS and hybrid products. A license holds a number of people: the owner, the person the license was issued to, and the members they invite. The seat limit is Max Seats on the plan, or the seats bought on a per-seat plan. It counts the owner, and 0 means no limit. With 5, the owner invites four people. With a Max Seats of 1, the license is the owner's alone and the portal shows no Members tab (a per-seat plan always shows it), unless the license already has members, for example from before it moved to a one seat plan: the owner can still see and remove them, and they are paused.
Roles
- Owner: the person the license was issued to. Manages the team and the billing, and holds the license's own key. Always holds a seat and is never paused.
- Member: uses the license with a key of their own, and manages their own devices. Cannot invite or remove anyone.
Teams used to have an admin role for members who could invite others. It was removed in v0.1.17: members who had it are now members, and only the owner manages the team. The invite endpoint (POST /api/v1/portal/seats/add) answers 400 to role: admin.
What owners and members see
| Owner | Member | |
|---|---|---|
| Key shown on the license | The license's own key | Their own key |
| Devices | Every device on the license, with the member who uses each | Their own devices, under My devices; the count beside All devices is the team's |
| Members | Everyone, with pending invitations, paused members and the seat count | The people who have joined |
| Invite, resend, cancel, remove | Yes | No |
| Billing actions | Yes, on Stripe licenses | No |
Your admins can see the team on the license page in the dashboard too. There they can remove a member or cancel an invitation, and reveal or reissue a member's key, but not invite anyone: invitations come from the owner.
Keygate sends the seat.added webhook when the owner invites someone new, or invites again someone who was removed, and seat.removed when a member is removed or an invitation is cancelled, followed by license.deactivated for each device that went with the member. Accepting an invitation, and being paused or let back, send no webhook.
Inviting team members
The owner adds people to a license by invitation:
- On the license, the owner opens Members, chooses Invite member and enters an email address.
- Keygate emails that address a one-time link to accept, valid for seven days.
- The invitee opens the link. Accepting signs them in to the portal, with an account made for them if they had none, and they open the portal to get their own license key.
- A pending invitation holds a seat: it counts toward the limit when the owner invites someone else. Cancel an invitation to free its seat.
- Resend sends the invitation again with a new link, and the earlier link stops working. An invitation past its seven days shows as Expired and can be resent.
- Inviting someone who is already on the team does nothing, and the owner cannot invite their own address.
- Invitations need a license in use: active, on a trial or past due until its end date plus the plan's grace days, or canceled until its end date. Otherwise the portal says the license can't take new members until it is active again.
- If every seat is taken when the invitee opens the link, for example because the limit was lowered after the invitation went out, they are told no seat is free. The invitation still stands: once the owner frees a seat or adds seats, the same link works.
- If the license is no longer in use when the link is opened, the invitation is invalid and the owner has to invite the person again.
- While a checkout that upgrades the license to a per-seat plan is open, nobody new can be invited. The checkout lapses within an hour if it is not paid.
Team members and their license keys
Every member who accepts an invitation gets a license key of their own. It is made the first time they open the portal after joining (or when an admin reveals it in the dashboard), and the portal shows it on the license with a note that it is theirs alone. Members enter this key in your app, not the owner's.
- A member's key works wherever the license's key works and opens the same license, with the same plan, features and end date. Your app makes the same calls with it.
- It keeps to the member's own devices and floating sessions: it verifies, deactivates and renews only the ones it activated. A device stays with the key that activated it, so a member's key on a device activated with another key on the license answers
409 DEVICE_HELD. The owner can remove that device in the portal, after which the member activates it as their own. - The device limit is the license's, shared by everyone on it, not a limit per member.
- The license's own key belongs to the owner and manages every device on the license. It does not change once issued; only an admin can reissue it, with Reissue key on the license page. That stops the old key at once and removes the devices activated with it, while members' own keys and devices stay.
- An admin can also reveal a member's key, or reissue it if it got out. The old key stops at once and its devices are removed. The member sees the new key in the portal but is not told, so let them know.
- Member keys work only while the product has seats, as a SaaS or hybrid product.
Before v0.1.17, members used the license's key. Their own key appears the first time they open the portal, and a device they had activated with the license's key moves, once, to their own key when they activate it with that key. See member license keys for how activate, verify and deactivate answer a member's key.
Removing a member
The owner removes a member with Remove member under Members, and an admin can do the same from the dashboard. The member loses access at once: their own key stops working, and the devices and floating sessions activated with it are removed, each sending license.deactivated. Their seat is free straight away. Removing works whatever state the license is in, so a lapsed or suspended license can still be cleaned up.
A member who also knows the license's key, for example from before members had keys of their own, can still use that key. Ask an admin to reissue the license's key in that case. A removed member who is invited again gets a new key.
Paused members
A license can end up holding more people than its seat limit. The portal and the dashboard's Change Plan refuse to go below the people on a license, and an invitation cannot be accepted while no seat is free, so this happens when the limit drops under the team:
- an admin lowers Max Seats on the plan;
- the seats on a per-seat subscription are lowered in Stripe itself;
- a trial moves to its fallback plan and that plan has fewer seats;
- the plan's price is changed in Stripe itself to one of a plan with fewer seats;
- a paid upgrade is undone (refund, unpaid or ended subscription) and the license goes back to its free plan, with people who joined while it was upgraded;
- the license is on a plan with Max Seats of 1 when Keygate is upgraded to v0.1.17, and already has members.
The owner holds one seat, the members who joined first hold the rest, and the members who joined last are paused. Pausing is worked out when the license is read, not stored, so as soon as a seat is free, because the owner removes a member, more seats are bought or the plan's limit goes up, the next member in line is back at once. Pending invitations do not count here: cancelling one frees a seat for a new invitation, but does not let a paused member back. The owner is never paused.
While a member is paused:
- their key refuses activation with
403 SEAT_PAUSED, and verification, floating checkout and usage refuse it as a key that may not be used, so their devices stop working online until they are back. An offline token issued before the pause runs to its own expiry; - they can still release their own devices, and sign in to the portal;
- the portal shows them their key with a notice that their access is paused and why, and does not show usage;
- the owner sees a Paused badge on the member and a note saying how many members are paused and how to let them back.
The team on the license page in the dashboard marks paused members, and so do the seat lists in the admin API (paused).
Who can sign in
By default anyone can request a login code. If the portal should only be for paying customers, open Settings, find Who can create an account and choose Only emails that hold a license. Keygate then stops sending codes to unknown addresses, which also keeps strangers from using your server to send mail. People who already have an account can always sign in.
A plan with self sign up is the exception. Its sign up form mails a code to any address, because claiming a license on a plan you opened is the sign up. Once the code is confirmed, the visitor holds a license and gets an account like any customer. An invited team member also gets an account when they accept the invitation, so the setting does not keep them out.
Frequently asked questions
Do team members share the license key?
No. Every member who accepts an invitation gets a license key of their own, shown to them in the customer portal. It works wherever the license's key works, but only for the member's own devices, and it stops working when the member is removed. The license's own key stays with the owner.
What happens when the owner removes a team member?
The member loses access at once: their own key stops working, and the devices and floating sessions activated with it are removed. Their seat is free for someone else. If they are invited again later, they get a new key.
Why is a team member paused?
The license holds more people than its seat limit, for example after the plan's Max Seats was lowered or seats were removed in Stripe. The members who joined last are paused until a seat is free. Removing a member or adding seats lets them back at once. The owner is never paused.
Why can't an invited person join the license?
Every seat is taken. The invitation stays valid for its seven days: once the owner removes a member or adds seats, the person opens the link again and joins. If the link has expired or no longer works, the owner sends the invitation again.
How do customers add or remove seats?
On a per-seat plan billed by Stripe, the owner uses Change seats on the license in the portal and sees the price before confirming. More seats apply once the difference is paid; fewer seats apply at once and are billed from the next invoice. For a license not billed by Stripe, an admin changes Seats bought in the dashboard.
Last updated October 26, 2026