Access and Sessions

A seller never has a password for the portal. Each organization picks one of two ways in, and all of its sellers use it: a personal access link that the operator generates in the Hub, or a one-time code that the seller requests and receives by phone or email. After sign-in, both methods lead to the same portal.

Signing in starts a session. The session renews itself quietly while the seller works, up to a maximum the organization sets, and a seller has only one session at a time. When a seller says they cannot get in, start with three questions: which sign-in method the organization uses, whether the session reached its end, and whether the seller opened the portal somewhere else.

This page is written for both sides: the operator who sets up access in the Hub, and the person who answers the seller when a screen says something unexpected.

Two Ways In

The method is set in the Hub, in Settings → Configuration → Seller portal (Settings is in the user menu; Configuration is the section in its sidebar), in the card's second section, Seller access ("How they sign in and how long their session lasts."). The field is Sign-in method. Seeing and changing these settings requires the configurations.write permission. Without it, Seller portal does not appear under Configuration. The rest of the card is covered in Configuring the Portal.

Under the field, the Hub describes the selected method. For Access token: "Each seller signs in with an access link you generate from their record." For OTP code: "The seller requests a code and signs in with it, with no links to hand out."

The method applies to the whole organization: there is no choosing a different method for one seller. When a seller arrives without a working session, or their session ends, the portal asks AltScore which method the organization uses. That is how it decides whether to show the code form or the link screen. Before sign-in it learns only three things about the organization: the sign-in method, the code channel and the session length. It receives customers, branding and everything else only after the seller is in.

Access Links

With Access token, every seller needs their own link. Links are managed in the sellers panel: in Sales routes, open the panel with the Sellers button (it shows how many sellers you have, for example Sellers (12)) and use the menu on the seller's row. Generating and revoking links requires the borrowers.write permission. Creating sellers and assigning them to routes is covered in Sales Routes and Sellers.

Generating a Link

The row menu shows Generate access for a seller who has never had access. For a seller whose access is active, revoked or expired, it shows Regenerate access.

The dialog is titled Generate portal access for a new access and Regenerate access otherwise. The line under the title depends on the case:

• New access: "This creates a personal link for {name}. With it they get into the seller portal without a username or a password."
• Active access: "This creates a new link for {name} and the one they have today stops working."
• Revoked or expired access: "{name}'s previous access no longer works. This creates a new link so they can get back in."

The dialog asks for two things:

The confirm button reads Generate link, or Generate new link when it replaces an existing link. If generating fails, the Hub shows the reason AltScore gives, or "The access could not be generated" when there is none.

The next dialog, Copy the link now, shows the Access link once, with a Copy button and the date the link expires. Copy the link before you press Done, I copied it. After the dialog closes, the link cannot be shown again. If it gets lost, generate a new one. The old link then stops working. If Copy shows "The link could not be copied", select the link in the field and copy it by hand before you close the dialog.

The link has the form /{tenant}/seller followed by the seller's personal access. A seller who opens it gets in without a username or a password.

Regenerating and Revoking

Each seller has one working link at a time. Generating a new link replaces the previous one. If the current access is still active, the dialog warns: "Once you confirm, the previous link stops working and any session the seller has open is cut off on their next action. You will have to send them the new link."

Revoke access appears only while the access is active. The confirmation dialog is titled Revoke {name}'s access. When you confirm, the link stops working immediately and any session the seller has open ends on their next action. The seller cannot see their customers until you generate a new link. Their routes and customers are not changed. If revoking fails, the Hub shows the reason AltScore gives, or "The access could not be revoked" when there is none.

Revoking deletes nothing, so use it when a seller leaves, loses their phone, or when a link went to the wrong place.

The Status Line

Under each seller's name, the panel shows the state of their access:

After the status, last sign-in on {date} or has not signed in yet shows whether the seller has used the access. If a link you sent days ago still shows has not signed in yet, check with the seller that it reached them.

One-Time Codes

With OTP code, there are no links. Generate access, Regenerate access and Revoke access no longer appear in the sellers panel, and the seller signs in with a code sent to the phone or email on their record. Two more fields appear in the Seller access section.

Channel and Template

OTP channel offers WhatsApp (the default), SMS and Email. The channel also decides how a seller identifies themselves at sign-in. With WhatsApp and SMS the seller types their phone number, and with Email they type their email address. So the phone or email on the seller's record in the Hub is the seller's identity when they sign in, and it has to be correct.

OTP template lists only the workspace's OTP templates for the chosen channel, which is why changing the channel clears the selected template. There is no default message: the code is sent with one of your templates or not sent at all. The hint under the field says so: "The code is sent with one of this workspace's OTP templates; there is no default message." If the channel has no templates yet, the hint reads "There are no templates for this channel yet." instead, and if the list could not be loaded, "We could not load the templates." With No template, sellers cannot sign in with a code, and the section shows a red alert: "Without a template selected, sellers will not be able to sign in with OTP." Save still works, but it shows a warning: "Saved, but without an OTP template sellers cannot sign in. Pick a template." The Manage templates link opens Settings → OTP Templates, where templates are created. The API side is described in OTP Templates.

If a seller tries to sign in while no template is set, the portal shows: "The administrator still needs to finish setting up code delivery. Let your supervisor know."

Which Sellers Can Receive a Code

Instead of a link status, each seller's row shows whether that seller can receive a code on the current channel:

With codes, the Hub shows no last sign-in date. last sign-in on {date} and has not signed in yet appear only with access links. With codes, the row only says whether the seller can receive a code.

A shared contact blocks both sellers, because a code has to go to exactly one person. The Hub does not save a new or edited seller whose phone or email another seller already uses ("Another seller already uses that email. The login identifies a seller by it, so two sharing one leaves both unable to sign in."), so a duplicate usually comes from older data.

Contacts are compared in a normalized form. Email ignores capital letters. For a phone, only the digits count: spaces, dashes and the plus sign are ignored. The digits themselves must match, though. A phone registered with its country code does not match the same phone typed without it: a seller registered as +54 9 11 5555 5555 who types 11 5555 5555 gets no code. Register phones in full international form, and tell sellers to type them the same way.

Signing In with a Code

The Contact Screen

When a seller at a code organization opens the portal without a session, they see Sign in to your portal.

• With WhatsApp or SMS, the field shows the placeholder "Your phone number" and the phone shows its number keypad. The help line reads "Enter the phone number your supervisor registered you with and we will send you an access code."
• With Email, the placeholder is "name@company.com", and the help line reads "Enter the email your supervisor registered you with and we will send you an access code."

The field has no visible label. Screen readers announce it as Phone number or Email address.

The button, Send me the code, stays disabled while the field is empty and shows Sending... while it works.

Before sending, the portal cleans up the phone number: it removes spaces, dashes, dots and parentheses. What remains must be 6 to 15 digits, with an optional + at the start. An email has to look like an address (something@something.something). If the entry fails these checks, a message appears under the field: "Check the number: digits only, with the country prefix if needed." or "Check the email: it does not look like a valid address."

When the request is accepted, the screen moves to the code step whether or not the contact belongs to a registered seller. The portal never says that a number is not registered: if it is not, the code just never arrives, and any code typed is reported as not correct. The screen stays on the contact step only when the request itself fails, for example because no OTP template is set, the sign-in method changed, or the server could not be reached. The message then appears under the field.

So when a seller reports that no code arrives, check in the Hub that the phone or email on their record matches what they type, country code included, and that their row status does not say the contact is missing or shared.

The Code Screen

Enter the code confirms where the code was sent. A phone number is shown as the portal cleaned it up, without spaces, dashes, dots or parentheses, and an email is shown as typed: "We sent a 6-digit code via WhatsApp to {identifier}." The SMS version says "via SMS", and the email version reads "We sent a 6-digit code to {identifier}." The screen has:

• A code field with the placeholder 000000, which accepts only numbers. It has no visible label; screen readers announce it as 6-digit code. On phones that support it, the code is filled in automatically from the SMS.
• Verify, which stays disabled until six digits are typed and shows Verifying... while it works.
• A resend link that counts down 60 seconds (Resend in {seconds} s) and then turns into Resend code.
• Change number or Change email, which goes back to the contact screen.

The code has 6 digits, expires after 10 minutes, allows 5 attempts and works only once.

After Resend code, only the newest code works on that screen. The portal checks against the latest request, so an older code that the seller receives later is rejected as not correct.

When Something Goes Wrong

Errors appear under the field:

For an expired code and for too many attempts, the portal also clears the code box, and the seller has to request a new code. The missing template is the only error the seller cannot fix: it is a task for the operator.

Signing In with a Link

The seller opens the link the operator sent. While the portal checks the access, a full-screen spinner shows Checking your access..., and then the portal opens. Opening the link is the whole sign-in.

The portal turns the link into a session once. In a normal browser tab, it then removes the personal access from the address bar, so the link is not left on screen and the Back button does not return to it. The browser's list of visited pages may still record the original address, so on a shared device treat that history like the link itself.

If a seller opens the portal without the link and without a session, they see a key icon and You need your access link: "Open the portal from the link your supervisor shared with you. That link carries your personal access." The screen has no form, because at a link organization there is nothing to type: the link is the way in. At a code organization, the same situation shows the code sign-in form instead.

The link keeps working until it expires or is revoked. The seller can open it again later, for example after their session reaches its maximum.

How Long a Session Lasts

Two settings in the Seller access section control session length. They apply to the whole organization and to both sign-in methods:

The two settings work like two clocks. The first is short and runs out often. When it does, the portal renews the session without the seller noticing, and the seller keeps working. Renewal keeps the same session, its original start time and its sign-in method, and it does not count as a new sign-in. Renewal also works on a session that has just run out. So a seller who stops for a while does not have to sign in again: the portal renews the session and retries the seller's last request once.

The second clock is long and never resets. When the maximum is reached, the portal stops renewing and the seller has to sign in again, either with a code or by opening their link. The maximum is always the one configured in the Hub, and AltScore enforces it when the session is renewed.

So the maximum is the setting that decides how often sellers sign in. A shorter session length makes the portal renew more often, but it does not ask the seller to sign in more often.

Under each field, the Hub explains it:

• Session length (minutes): "How long a session lasts before the portal renews it on its own. The seller sees nothing and keeps working. A shorter value narrows the window someone holding the seller's phone could use."
• Maximum before signing in again (hours): "How long the session can keep renewing before the seller has to sign in again (with their code or their link), however long they have been working."

Keep in mind that renewal also works on a session that has just run out. So for an open session, on the seller's phone or in anyone else's hands, the limit that counts is the maximum: a shorter session length does not end that session any sooner.

A value outside the allowed range turns the field red and replaces its hint with "Must be a whole number between {min} and {max}." The session length also has to be shorter than the maximum, meaning the minutes must be below the hours multiplied by 60. Otherwise Save is blocked with "The session cannot last longer than the maximum. Lower the minutes or raise the hours."

Changes to these two settings reach sessions that are already open, because both are read again at every silent renewal. Lowering Maximum before signing in again (hours) ends, at their next renewal, every open session older than the new maximum. Raising it lets open sessions keep renewing up to the new maximum, as long as the seller uses the portal before the old maximum passes. A new Session length (minutes) applies from each session's next renewal.

If the seller reopens the portal later in the same browser, in a normal tab, the session resumes without a sign-in. A session that ran out is renewed and the seller continues, until the maximum or another event ends it.

One Session per Seller

Each seller has one active session. Signing in on another device, whether by opening the link or by entering a code, closes the previous session. The other device finds out on its next action. At a link organization it shows This session was closed. At a code organization it goes back to the code sign-in form.

Renewal does not close any session, so two tabs in the same browser can keep working side by side. Only a new sign-in closes the previous session.

Watch for one case: a seller with the portal open both in an app and in a browser keeps signing themselves out, because each sign-in closes the other session. Nothing is broken. Ask the seller to use just one.

When a Session Ends

What the seller sees when a session ends depends on the sign-in method.

At a code organization, the following situations all go straight to the code sign-in form, with no screen in between: a session that expired, a session that reached its maximum, a session closed by another device, revoked or expired access, and a visit with no session. The seller signs in again and continues.

At a link organization, the portal shows a screen with an icon, a title and a message. For the situations above, the message asks the seller to open their link again. When the access was revoked or has expired, it asks them to request a new link from their supervisor instead. There is no button, because only the seller can open a link. The portal is in Spanish by default, so the table also gives the Spanish title, which is usually what a seller reads out to support.

Generating a new link closes the seller's open session. On their next action they see This session was closed, whose message talks about another device. Nobody else opened their access: send them the new link.

In a normal browser tab, Your session reached its limit appears when the seller is working in the open portal and acts within about an hour after the session stops renewing. If they reopen the portal within that hour instead, they see Your session expired. Later than that, the browser no longer holds the session, so they see You need your access link. At a code organization, all of these lead to the code form.

The last four screens look the same for both methods. If the phone is offline when any of these screens would appear, the seller sees No connection instead.

Sometimes the portal cannot determine which method the organization uses. In that case, the expired, maximum, closed-elsewhere and expired-access screens offer a Log in again button (Volver a ingresar) and show the general version of their message instead of the one about reopening a link:

• Your session expired: "You were away for a while. Log in again to pick up where you left off."
• Your session reached its limit: "For security, this session cannot be extended any further. Log in again to continue."
• This session was closed: "Your access was opened on another device and this session was closed. Log in again to continue on this one."
• Your access expired: "The link you are using is no longer valid. Ask your supervisor for a new one."

In the same situation, a visit with no session shows You need your access link with no button, even at a code organization. Reloading the page asks again.

When the seller presses the button, the portal checks the method again. It opens the code form or shows the link message. If it still cannot tell, it stays on the same screen and the seller can try again.

A revocation reaches the seller on their next action, not the moment the operator confirms it. Until then, the screen they have open stays as it is.

The errors the portal shows elsewhere, while the seller works, are collected in Errors, Warnings and Limits.

Embedding the Portal in Your Website

The portal can run inside an iframe on your website, but only from sites enabled for your deployment. By default, no site can embed it. To embed it in yours, ask AltScore to enable your site.

When embedded, the session lives only in the page's memory and is never saved in browser storage. As a result, the session does not survive a reload the way it does in a normal tab:

• With access links, reloading the iframe signs the seller in again from the link. For that to work, the link stays in the iframe's address. So the page that embeds the portal holds the seller's personal access, and should be treated with the same care as the link itself.
• With codes, reloading the iframe brings back the code sign-in form, because there was no saved session to resume.

Things to Know

There is no logout button. At a link organization this is deliberate: the link is turned into a session once and then leaves the address bar, so the session is the seller's way in until it ends. At a code organization there is no logout either. On a shared phone, the session ends at the maximum, when the seller signs in somewhere else, or when the operator revokes the access or generates a new link (links only).

Code organizations have no Revoke access in the Hub. Revoking would not lock a code seller out anyway: it only closes their current session on their next action, and they can request a new code right away. So at a code organization a session lasts until the maximum, until a new sign-in, or until the seller is deleted (a seller can be deleted only once they have no routes). To stop a seller from getting new codes, change or remove the phone or email on their record. That does not end a session that is already open.

Delegated OTP delivery is not available for seller sign-in. Seller codes go out by WhatsApp, SMS or email only. The delegated channel described in Delegated OTP delivery is used only by conversational flows.

The country code is part of the phone number. Register sellers' phones in full international form. A seller who types the number without the prefix it was registered with does not receive a code, and the portal does not tell them why.

Switching the sign-in method does not close open sessions. Sellers start using the new method the next time they sign in. A seller who is on the code screen at the moment of the switch sees "The sign-in method changed. Reload the page to continue." After a switch to codes, opening an old link brings up the code sign-in form. After a switch to links, generate a link for every seller before their current sessions end. Otherwise they reach You need your access link with nothing to open.