Docs/Guides
Single sign-on
Your application signs a short token saying who somebody is. We verify it against a secret only your workspace holds, and start a session. No XML, no metadata exchange, no discovery document.
What you need
Single sign-on is on the Plus and Pro plans. Turn it on from Settings · Sign-in and privacy in your workspace, under Single sign-on. You will get a signing secret, shown on that page.
The secret is the whole of the trust. Anybody holding it can sign anybody in as any address, so it belongs in your server's configuration and never in a browser, a mobile app, or a repository. Rotating it from that page takes effect at once and breaks every token already minted, which is what you want the moment you think it has leaked.
The token
A JWT signed HS256 with your secret. Four claims are required, and a token missing any of them won't sign anyone in:
{
"sub": "8f14e45f", // your own id for this person, any string
"email": "[email protected]", // who to sign in, lowercased by us
"iat": 1724500000, // a moment ago, never ahead of our clock
"exp": 1724500120 // a minute or two out
}subrequiredYour own identifier for this person. We don't interpret it. It's required so that an email address is never the only thing a token vouches for.
emailrequiredWho to sign in. It's lowercased first, so different capitals never create a second person. It has to be an address we can send to: plain ASCII, with an international domain written in its
xn--form. Anything else is turned away like a bad signature, with the same message.iatrequiredWhen the token was issued, in seconds. It can be up to two minutes old, but never ahead of our clock, not even by a second. If your server's clock runs fast, every sign-in fails. Setting it thirty seconds in the past avoids the problem entirely.
exprequiredExpiry. Set it a minute or two out. A long expiry does not buy you anything: the two-minute rule above is ours and you cannot relax it.
Add a name and we use it the first time we see somebody
It becomes their display name when the token creates their account. After that the name is theirs: later tokens don't change it, and neither does signing in to another workspace. The spelling they first arrive with is the one that sticks.
That's all a token can do to an account. A person has one name across every workspace they belong to, so a directory that calls someone "R. Okafor" shouldn't rename them everywhere else.
A name we can't use is dropped, but the sign-in still goes ahead. Anything that isn't text, or is only spaces, is ignored, and a name longer than 200 characters is cut to 200. Either way the person is signed in, and can set their own name in the product.
Add a user_segment and we use it every time
Unlike name, this claim is meant to change, so we read it again at every sign-in and keep whatever you sent last. A name is who someone is. A user segment is what they're worth to you this month.
{
"sub": "u_912",
"email": "[email protected]",
"iat": 1756400000,
"exp": 1756400120,
"user_segment": {
"id": "cus_9F2k", // required: your own id for the segment
"name": "Globex",
"label": "Enterprise", // your word for their tier, optional
"value": 200000 // minor units: 200000 is $2,000.00
}
}id is required and is your own identifier for the segment: a Stripe customer id, your own org id, whatever you already store. We key on it and never on the name, so renaming a segment in your system renames it here instead of creating a second one and splitting its votes. A claim with a name and no id is ignored.
value is in minor units: 200000 is $2,000.00, and it is what this segment pays as a whole. Send it consistently: we add these together across segments, so a mixture of monthly and annual figures produces a number nobody can explain.
The claim has no currency. A segment created from a token takes your workspace’s currency, and an existing segment keeps the one it has. A segment your team set to GBP stays in GBP, however many of its people sign in. A token can’t change a segment’s currency. If the figure you send is in a different currency, fix it on the segment, not in the token. We convert currencies to sort boards and total your workspace, so a figure in the wrong currency throws off every sum.
It sets the segment’s own figure, which suits a company: one contract, however many of its people sign in. A segment whose members each pay their own amount works differently, and a token can’t price it. Those figures come from the segment’s own feed, or from someone typing them in. If you send a figure for one anyway, the whole claim is dropped, so the person isn’t linked to the segment either. If someone isn’t showing up in a segment you expected, check this first.
name and label are optional. A user segment can be a company of twelve people, or one subscriber or donor. We don’t assume which, and your team sees the name you send or the one they type.
Leaving a field out keeps what is already there. A field you did not send is not a field you cleared, so omitting label or value leaves whatever your team typed or your last assertion set. Sending an empty label does clear it, because that is you saying so. The one exception is name: leave it out and the segment is renamed to its own id, so send it every time.
An unusable one costs the segment and never the sign-in, exactly as an unusable name does. A value that is not a number is dropped, and so is a negative one.
User Segmentation is on Pro and single sign-on is on Plus, so a Plus workspace can send this and have it quietly ignored. That is deliberate: your customers must not meet a failed sign-in over a tier, and the person who can act on it is you. Nothing else changes.
Anything else you add is ignored.
Why two minutes
A token is made at the moment of a redirect and used one step later, so a short window costs nothing. A long one would leave a working credential in your users’ browser history, your access logs, and any referrer header the next page sends. A token also isn’t single use: anyone holding one inside its window can use it again as that person, so the window is the only limit. Clock differences aren’t a reason to widen it, and a clock ahead of ours is turned away outright.
Sending somebody in
Link or redirect to /auth/sso on your workspace host with the token in the query string.
https://acme.heedpost.com/auth/sso?token=<jwt>&next=/roadmap
The path is /auth/sso and not /sso, which is worth a sentence because the shorter one is the obvious guess. Every document under /auth/ is served private, no-store, and this URL carries a live credential in its query string: anywhere else a shared cache would key an entry on it.
import jwt, time
def heedpost_url(user, next_path="/"):
# Thirty seconds back: we refuse an iat ahead of our clock, with no tolerance.
issued = int(time.time()) - 30
token = jwt.encode(
{"sub": str(user.id), "email": user.email, "iat": issued, "exp": issued + 120},
HEEDPOST_SSO_SECRET,
algorithm="HS256",
)
return f"https://acme.heedpost.com/auth/sso?token={token}&next={next_path}"import jwt from "jsonwebtoken";
export function heedpostUrl(user, nextPath = "/") {
// Thirty seconds back: we refuse an iat ahead of our clock, with no tolerance.
const issued = Math.floor(Date.now() / 1000) - 30;
const token = jwt.sign(
{ sub: String(user.id), email: user.email, iat: issued, exp: issued + 120 },
process.env.HEEDPOST_SSO_SECRET,
{ algorithm: "HS256" }, // no expiresIn: the payload already carries exp
);
return `https://acme.heedpost.com/auth/sso?token=${token}&next=${nextPath}`;
}Mint the token when somebody clicks through, not in advance. A token in a page that was rendered ten minutes ago is a token that has expired.
next is optional and is where they land. It must be a path on your board, not a URL: /roadmap, /changelog, /p/<id>. Leave it out and they land on the board index.
Any other path is ignored, and the sign-in still works. If we don’t accept a next, the person lands on the board index, signed in, instead of a mistyped link turning into a failed sign-in. So if people arrive at the index when you expected the roadmap, the token was fine and the path wasn’t.
What gets dropped is anything that leaves your board or reads as though it might. Absolute URLs and protocol-relative ones (//host), anything with a scheme, a colon or an @ in the path, backslashes, .., control characters, and the encoded spellings of all of those. A query string is fine and may contain anything printable: /b/features?tag=ux works.
The same token in the widget
If you embed the feedback widget, the token goes in data-identity on the script tag instead of in a URL. It is the same token, signed the same way, and the two functions above mint it unchanged.
<script src="https://acme.heedpost.com/widget.js"
data-board="feedback"
data-identity="<jwt>"
async></script>The two minutes start when you render the page, so for a page somebody might open later, hand window.Heedpost.identify a function instead. The widget guide has the details, the twelve-hour session and the functions that open and close the panel.
What a signed-in person gets
They are added to your workspace as an end user: they can post, vote and comment. An assertion says somebody is a person, not that they are on your team, so admins and members are still invited from Settings · Team and roles or promoted there.
Someone already on your team keeps their role. New people are created as end users, but a token never demotes anyone, so your own admins can sign in through your application without losing anything. That’s what makes the next step safe to turn on.
An SSO session can’t change the account behind it. A HeedPost account is one account across every workspace it belongs to, and your token proves an address to you, not that the person owns the mailbox. So a session started this way can’t rename the person, change or remove their photo, or schedule their account’s deletion. Those need a sign-in that proved the mailbox: an emailed link, or Google.
Making it the only way in
Once it works, you can turn on Make it the only way in, in Settings · Sign-in and privacy. Emailed links and Google then stop working for this workspace, and everyone arrives through your application.
An invitation still lets its person in. Someone an admin invites from Settings · Team and roles joins by the link in that email, in the role the admin chose, and signs in through your application from then on, so they need an account there too.
That setting needs a start URL. Someone who lands on your board without a session has to be sent somewhere, and with nowhere to send them, nobody could get in. Point it at the page in your application that makes a token and redirects.
Two things keep you from being locked out. If your workspace moves to a plan without single sign-on, the requirement is lifted instead of shutting everyone out. Your secret is kept, so upgrading again needs no new setup. And if nobody can get in, email us. We can lift the requirement from our side without touching your secret or your settings.
When a sign-in fails
A token that doesn’t work gets a 403 with one sentence, and it’s the same sentence whatever went wrong. Telling you which part of a token failed would tell an attacker too. Work through it from your side:
403The signature, a missing claim, an
iatoutside the window, an expiredexp, or an address that is not one. Check the algorithm isHS256, that all four claims are present, and that your clock is not ahead of ours.422The token isn’t a plausible shape: shorter than 16 characters or longer than 4096. It was never checked, so your signer is sending something empty or cut short. The claims inside aren’t the problem.
402The workspace’s plan doesn’t include single sign-on. This answer is different from the others because it’s about your plan, not the token, and you can act on it.
429Too many sign-ins from one place. The limit is per calling address, not per workspace, so an office behind one connection shares it. Make a token when someone clicks, not in a loop.
If tokens that used to work stop working all at once, the likeliest cause is a rotated secret, and the second likeliest is a clock that has drifted.
What this is not
This is not SAML and not per-workspace OIDC. There is no metadata exchange, no certificate, and nothing to upload. If you need SAML specifically, tell us what for.