Skip to main content
Advanced For developers who ship a page for a project that is not open to everyone. After this page your page handles a password, a sign-in and their failures without surprising the viewer. Who may watch a project is set in the dashboard, not in your code: see Security and access control and SSO access. Your page follows that setting. With the default auth you write no access code for a public project.
Moving a page from v1? Your page follows the project’s access setting: check it first, so a password or sign-in screen does not surprise your viewers. See Migrating from v1.
The offline check comes first. A viewer is never asked for a password, or sent to sign in, for a project that cannot stream.

Which screens are yours

Password projects

On a password project create() does not throw. It resolves, and stream.state.kind is 'awaitingPassword'. No has been requested and no GPU is in use.
Mount the ready-made screens. The password screen is one of them, with the project’s logo, the wrong-password message and the lockout countdown.
main.ts
Open the page for a password project. You see “This stream is protected”, a password field and Continue. The right password starts the stream.

The awaitingPassword state

The state object is { kind: 'awaitingPassword' }, with up to four extra fields. With none of them, the stream is simply waiting for a password: show the field.
boolean
true: the last password was refused. Say so, and let the viewer try again.
boolean
true: too many wrong attempts. This is a soft lockout: the right password is still accepted, so keep the field usable.
boolean
true, together with locked: every attempt is refused for now. Disable the form.
number
How long the lockout lasts, in seconds, when the server said. The SDK does not change the state when the time is over: use your own timer to enable the form again.

submitPassword(password)

Call it with what the viewer typed. It returns a promise.
A wrong password does not reject. Read the result from the state, not from a catch.

Remembering the password

After a correct password the SDK keeps it for this browser tab only (sessionStorage) and tries it silently on the next create(). A page reload does not ask again.

Ask before you start

If your page asks for the password before it starts the stream, pass it with auth:
A password from your own form
A wrong one lands in awaitingPassword with wrong: true, exactly as above. The same form can then retry with submitPassword().
Never write a project password in your page’s code. Anyone can read a page’s code. Pass only what the viewer typed.

Single sign-on

With the default auth there is nothing to write for the normal path. The SDK does the redirect and finishes the sign-in.
1

Your page calls create()

The SDK sends the browser to the sign-in page. Just before the page navigates away, create() rejects with AuthError, kind sso-required. Ignore that one.
2

The viewer signs in

The viewer comes back to the same address of your page: origin, path and query string. A #fragment is not kept.
3

Your page loads again and calls create() again

The address now carries a single-use grant, ?ssoGrant=. The SDK uses it, removes it from the address bar, and starts the stream.
A viewer who is already signed in at your identity provider sees the stream after a short redirect, without typing anything.
Three things to know:
  • Your page’s domain must be on the project’s allowed domains list. Single sign-on returns the viewer only to a page on that list. Set it under Domain restrictions: see SSO access.
  • The SDK uses two query parameters, ssoGrant and ssoError. It reads them and removes them from the address bar. Do not use these names for parameters of your own.
  • A reload starts the sign-in again. The grant works once. When the viewer is still signed in at your identity provider, the redirect is usually instant.

When the sign-in fails

A sign-in that was refused, or a grant that was already used or has expired, rejects create() with AuthError, kind sso-failed.
string
One of a fixed set of sentences for the viewer, for example “Sign-in was cancelled or refused. Please sign in again.” or “Your account is not allowed to open this stream. Ask the project owner for access.” Show it.
string
Navigate here to start the sign-in again.
string
The sign-in service’s error code. For your logs, not for the viewer.
Handle both sign-in errors
showMessage and showSignInButton are your own functions.
On sso-failed, show a button. Do not navigate to ssoStartUrl by yourself: a viewer whose account is not allowed would go round in a loop.

Do the redirect yourself

Use redirect: 'manual' when your page should decide when to leave: a single-page app with a router, or your own “Sign in” button. The SDK then never navigates.
Manual redirect
After the sign-in, the viewer lands on your page with the grant in the address, and the same create() call starts the stream.

Your app only

Your app only is not available yet. Until it is, restrict a project with a password or with single sign-on.
Your app only (not available yet) is the access setting for a site that already signs its own users in. In this mode a stream starts only from a page that passes a ticket requested by your server. No password and no Streampixel sign-in is involved. The SDK’s side of it is in the API already:
1

Your server requests a ticket

Behind your own sign-in check, your server calls POST https://platform.streampixel.io/api/v1/stream/ticket with the project’s server key in the x-server-key header.
server.ts
2

Your page passes the whole response to the SDK

Pass a function. The SDK calls it at create(), and again when it opens a fresh session by itself.
page.ts

All auth values

Exactly one is active per stream.
default
Follows the project’s access setting, as in the table at the top of this page.
password: string
The viewer already typed the password into your own form. A wrong one resolves in awaitingPassword with wrong: true.
redirect?: 'auto' | 'manual'
The same as 'auto' on a single sign-on project. With redirect: 'manual' the SDK does not navigate: create() rejects with kind sso-required and ssoStartUrl, and your code navigates.
ticket: object | string | function
Your app only (not available yet): the whole response of your server’s ticket request, or a function that returns it.
An auth.mode other than these four, or mode: 'password' without a password string, rejects create() with a TypeError before any network call.

Troubleshooting

The project’s access setting is Password. Your page follows the project’s setting. Change the setting in the dashboard, or keep it and give your viewers the password.
That is the normal start of a sign-in. create() rejects just before the browser navigates to the sign-in page. Ignore that error in your catch.
Check that your page’s domain is on the project’s allowed domains list (Domain restrictions), and that your page calls create() again when it loads with ?ssoGrant= in the address.
A wrong password is not an error. create() and submitPassword() both resolve, and the state is awaitingPassword with wrong: true.
The SDK does not leave the hard lockout by itself. Start a timer for retryAfterSec seconds and enable the form when it fires, as in the example on this page. @streampixel/ui does this for you.
Too many requests came from the viewer’s network. err.retryAfterSec says how long to wait. See Errors and disconnects.

Next steps

Errors and disconnects

Every AuthError kind and what to show for it.

Ready-made screens

The password screen that @streampixel/ui draws.

Reliability

One level up: what the SDK does when a session has to be restored.

Options reference

auth, rememberPassword and every other option.