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.

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.

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.

We treat this as an opaque string.

For additional privacy, you can skip this entirely or provide a hashed value. Be aware that if you provide a hashed value during registration, you'll need to do the same hashing during authentication. If omitted, you'll need to send an id during authentication, which typically means a roundtrip to your backend.

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 should have a stable identifier, such as (but not limited to) a database primary key. This is set up as the id field on a User Account (below). A User also may have a handle, which is a "semi-stable" identifier like a username. The handle can be used during authentication by the Client APIs to avoid a roundtrip to your service to look up the id.

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.