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 Credentials to a User Account, and verifying Auth Tokens.

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.

Passkeys also only work on sites served over https://, with an exception for localhost. If your dev environment isn't accessible on localhost, it must run over TLS.

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.

Only use the user field in our API response when determining who is present. A clever user or a bug in client code could lead to getting a token for a different user than is indicated by form fields. Our response is based on cryptographic proof of possession.

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.