auth you write no access code for a public project.
Which screens are yours
Password projects
On a password projectcreate() does not throw. It resolves, and stream.state.kind is 'awaitingPassword'. No has been requested and no GPU is in use.
- With @streampixel/ui
- Your own form
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.
true: too many wrong attempts. This is a soft lockout: the right password is still accepted, so keep the field usable.submitPassword(password)
Call it with what the viewer typed. It returns a promise.
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 withauth:
awaitingPassword with wrong: true, exactly as above. The same form can then retry with submitPassword().
Single sign-on
With the defaultauth there is nothing to write for the normal path. The SDK does the redirect and finishes the sign-in.
Your page calls create()
create() rejects with AuthError, kind sso-required. Ignore that one.The viewer signs in
#fragment is not kept.Your page loads again and calls create() again
?ssoGrant=. The SDK uses it, removes it from the address bar, and starts the stream.- 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,
ssoGrantandssoError. 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, rejectscreate() with AuthError, kind sso-failed.
showMessage and showSignInButton are your own functions.
Do the redirect yourself
Useredirect: '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.
create() call starts the stream.
Your app only
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:How a page passes a ticket (not available yet)
How a page passes a ticket (not available yet)
Your server requests a ticket
POST https://platform.streampixel.io/api/v1/stream/ticket with the project’s server key in the x-server-key header.Your page passes the whole response to the SDK
create(), and again when it opens a fresh session by itself.Rules for the ticket (not available yet)
Rules for the ticket (not available yet)
All auth values
Exactly one is active per stream.
awaitingPassword with wrong: true.'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.auth.mode other than these four, or mode: 'password' without a password string, rejects create() with a TypeError before any network call.
Troubleshooting
A password screen appeared and I did not expect one
A password screen appeared and I did not expect one
The console shows AuthError sso-required and then the page leaves
The console shows AuthError sso-required and then the page leaves
create() rejects just before the browser navigates to the sign-in page. Ignore that error in your catch.After signing in, the page reloads and no stream starts
After signing in, the page reloads and no stream starts
create() again when it loads with ?ssoGrant= in the address.My catch block never sees a wrong password
My catch block never sees a wrong password
create() and submitPassword() both resolve, and the state is awaitingPassword with wrong: true.The form stays disabled after a lockout
The form stays disabled after a lockout
retryAfterSec seconds and enable the form when it fires, as in the example on this page. @streampixel/ui does this for you.create() rejects with rate-limited on a public project
create() rejects with rate-limited on a public project
err.retryAfterSec says how long to wait. See Errors and disconnects.Next steps
Errors and disconnects
AuthError kind and what to show for it.Ready-made screens
@streampixel/ui draws.Reliability
Options reference
auth, rememberPassword and every other option.