Introduction
Welcome to SnapAuth!
This is our quick start guide. It'll help get you started, but you'll want to also see our Client API and Server API documentation.
Client APIs are used to start browser/device-native WebAuthn flows. They return one-time-use tokens that you send to your backend to use with the Server APIs.
Server APIs are used for finalizing and verifying critical data,
such as attaching Credential
s to a User Account
, and verifying Auth Token
s.
Quick Start
If you're just getting started, you're in the right place!
There are two things you'll probably want to start with: registering a credential, and authenticating with it!
API Setup
If you haven't done so already, you'll want to create a SnapAuth account. This will grant you a pair of API keys: one publishable (for the Client APIs) and one secret (for the Server APIs). Be sure to provide the domain you're integrating with - passkeys and WebAuthn are domain-specific, and nothing will work if they don't match.
See the guides for client and server SDK setup and configuration.
Registering a Credential
This associates a passkey with one of your users.
1) Run the snapAuth.startRegister()
SDK call on your frontend,
and send the token it returns to your backend.
The token represents a pending Credential.
2) Use the token with the attach registration Server API to associate the Credential with one of your Users.
You may do this at any point in your service's flow; it does not need to be when the first signs up (and if you're integrating SnapAuth into an existing app, it probably won't be). Often this will be on a settings screen where a user would configure other auth preferences.
Authenticating with a Credential
This lets a user Authenticate with one of their existing Credentials.
1) Run the snapAuth.startAuth()
SDK call on your frontend,
and send the token it returns to your backend.
The token represents someone's credential.
2) Use the token with the verify token Server API to get back cryptographically verified information about the authenticating user.
3) Inspect the user
object in the response (and, optionally, other fields) to proceed.
Use the user.id
field to determine who has just authenticated - this will match the value you previously provided during registration.
This might mean starting a session, generating a JWT, allowing a procedure to run, or anything else.
Like registering a credential, this can be done at any point in your application's flow. Typically this is going to be on a sign-in screen, but we do not restrict to any specifics.
API Keys
In the SnapAuth dashboard, you'll find a set of API keys.
The publishable key
is used by Client APIs, and the secret key
is used by Server APIs.
Both use HTTP Basic
auth, which will be configured for you automatically if using an SDK.
As the name implies, it's ok to share and embed your publishable key. Similarly, you MUST protect your secret key(s): it's what safeguards registration.
Browser Stats
<script
src="https://api.snapauth.app/stats.js"
data-dedupe
data-key="<your publishable key>"
defer></script>
To use our free passkey browser statistics program, add this JavaScript snippet to any page you want to measure.
It's lightweight (~0.5kb zipped) and collects no PII and no page-specific data about your site. We actively remove referrer data and credentials so we never get access to it.
Configuration
Attribute | Value | Purpose |
---|---|---|
data-key |
string |
Your publishable key |
data-dedupe |
none | De-duplicate stats submissions client-side |
All configuration data is optional.
If you want to contribute to global stats without the data being attached to your site at all, you may omit data-key
.
Data for your domain(s) will not be available in the dashboard.
data-dedupe
is optional, but recommended.
If set, we'll set a bit in sessionStorage
once stats have been sent during a session.
If omitted, we will leave absolutely no trace in any client storage, but your users may send stats more often than they'll be used, leading to wasted bandwidth.
We will still de-duplicate data server-side.
Terminology
It's helpful to be familiar with some common terms used in our documentation. This matches and summarizes the W3C WebAuthn spec when applicable.
AAGUID
Authenticator Attested Globally Unique ID. The AAGUID is a 128-bit identifier indicating the make and model of the authenticator.
Authentication
The act of using a previously-saved Credential. This performs a test of user presence and uses a cryptographic signature to demonstrate proof of possession of a private key.
Often indicates a second factor was used (either knowledge or biometrics, depending on device) depending on the User's device and WebAuthn settings.
Credential
A set of data including a cryptographic public key. We associate Credentials with User Accounts during Registration for later use during Authentication.
Credentials do not contain Personally Identifying Information (PII) or biometric data.
Handle
This is any "semi-stable" identifier that a user uses to sign in to your service. Commonly this is a username or email address, but it can be any value you want, or skipped entirely.
Handles are used during authentication to look up a user from client-supplied data in order to avoid a roundtrip to your server to get their id.
Passkey
A passkey is a specific kind of Credential that supports backups and autofill. It's commonly the user-facing term for WebAuthn.
Unless stated otherwise, we'll typically use the term passkey
to refer to any sort of WebAuthn Credential.
This includes actual passkeys, FIDO-U2F devices (e.g. YubiKeys), TPM elements, and more.
Registration
The process of creating a credential.
User
One of your users/accounts, as defined by your service.
A User must have a stable id
.
A User also may have a handle
, which is a "semi-stable" identifier like a username.
User ID
Your user's stable identifier, such as a database primary key. We treat this as an opaque string, with a max of 255 characters.
This value will be returned to you during authentication.
User Handle
See handle.
User Account
This is our representation of one of your Users.
Each User Account has an id
and (optionally) handle
that you provided, as described above.
Additionally, each User Account is associated with a number of Credentials.
This allows the your User to authenticate; when this happens, this is the data returned.
Web Authentication (WebAuthn)
Web Authentication is the underlying technology that powers SnapAuth. It's an open standard implemented by browsers that allow authenticating with public-key cryptography. Native apps (iOS/Android) have equivalent APIs.