NAV
Web iOS Android

Introduction

Welcome to SnapAuth!

This documentation is for our Client APIs. You can browse our Server API documentation here.

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.

Setup

Installation

// Node
npm i --save '@snapauth/sdk'
// UMD
<script src="https://unpkg.com/@snapauth/sdk"></script>
// Coming soon!
// Coming soon!

Client code should use the official SDKs, available from the platform's package manager.

We strictly follow semantic versioning, so you can upgrade confidently within a major version. It's strongly recommended to keep your SDK(s) up to date.

SDK Setup

// npm
import { SDK } from '@snapauth/sdk'
const snapAuth = new SDK('pubkey_xxxx')
// UMD
const snapAuth = new SnapAuth.SDK('pubkey_xxxx')
// Coming soon!
// Coming soon!

Client SDKs will use your publishable API key. You may safely embed it in whatever way is most convenient for you.

The publishable key is specific to an environment - i.e. a domain. This is a requirement for the WebAuthn protocol - Credentials are bound to a specific domain.

Registration

let name: string // Some value from your app. The user will see this during sign-in.

const registration = await snapAuth.startRegister({ name })
if (registration.ok) {
  const token = registration.data.token
  // Send token to your backend along with other relevant data
} else {
  // If desired, inspect registration.error and decide how to proceed
}
// Coming soon!
// Coming soon!

Wrapped Response (registration.data)

{
  "token": string,
  "expiresAt": Timestamp,
}

Registration is the process of creating a Credential for a User Account.

Users can have multiple Credentials, and each one must be registered independently. To start the process of creating a Credential, use the SDK's startRegister method. On success, it will return a registration token - this is a one-time-use token which you must send to your backend to attach to the user.

Field Type Required? Usage
name string yes Name for the user. This is for client-side display; it is not sent to or retained by us.
id string no Your stable identifier for the user
handle string no Your "handle" for the user (e.g. username)
displayName string no Display name for the user. Defaults to the value of name. Note: browser sign-in tends to display name and ignore displayName

Both id and handle are unused right now, but reserved for future verification during the server-side component.

Authentication

let id: string|null
let handle: string|null

const auth = await snapAuth.startAuth({ id, handle })
if (auth.ok) {
  const token = auth.data.token
  // Send token to your backend along with other relevant data
} else {
  // If desired, inspect registration.error and decide how to proceed
}
// Coming soon!
// Coming soon!

Wrapped Response (auth.data)

{
  "token": string,
  "expiresAt": Timestamp,
}

Authentication is the process of using a previously-registered credential. This may be to sign in to your application, or to elevate permissions for a sensitive action.

Like Registration, this API will return a one-time-use token which you must send to your backend to verify.

Request

Field Type Required? Usage
id string no* Your stable identifier for the user
handle string no * Your "handle" for the user (e.g. username)

Response

Field Type Meaning
token string The one-time-use token to send to your server to verify
expiresAt Timestamp When the token will expire.

* You must provide either id or handle. If you provide both, only id will be used.

Autofill-assisted requests

import { AuthResponse } from '@snapauth/sdk'

const onAuthenticate = async (auth: AuthResponse) => {
  if (auth.ok) {
    const token = auth.data.token
    // e.g.
    const response = await postToYourBackend('/endpoint', { token })
    // .. Do whatever you need to!
  }
}

snapAuth.handleAutofill(onAuthenticate)

// On the page, you must also have a webauthn input:

<input type="text" autocomplete="username webauthn" />
// Coming soon!
// Coming soon!

For devices and platforms that support it, you can set up autofill-assisted requests. This will prompt the user to authenticate without having to type anything in - they only have to approve the action.

There are two setup steps:

Tips

SDK Design

const result = await snapAuth.someAction(...)
// result has an `errors` property, containing 0 or more errors
if (result.ok) {
  // result has a `data` property, which contains the documented response
} else {
  // `errors` is guaranteed to have at least one entry
}
// Coming soon!
// Coming soon!

The SDKs are designed so that following the "happy path" will be most reliable. We also focus on type safety so that you can leverage the tooling you're already familiar with. Responses use a Result type to indicate success or failure.

You should never need to run SnapAuth Client SDKs with try/catch blocks.

Token Exchange

The Client SDKs return a one-time-use token, which you must be sent to your backend for further use. These tokens are exchanged with our Server SDKs to complete the registration and authentication processes.

Defensive Coding

Results may contain errors even if they are ok. These could hint at an outdated SDK, incorrect usage, deprecation, or something else.

Browser Usage

Browsers require the WebAuthn APIs to be used only in response to a user gesture, such as onClick or onSubmit.

API Format

Types

Id

string: Your stable identifier for a user (e.g. database primary key). Cannot be changed. Max 255 characters

Handle

string A semi-stable identifier for a user (e.g. username). Can* be changed. Max 255 characters

* change handle API coming soon

Timestamp

integer: Unix Timestamp, in seconds

Error

object: Information about an error or warning

Field Type Meaning
code string A machine-readable code. See below
message string A human-readable description of the error. This is intended primary for developers, not end-users

Errors

Code Meaning
timeout The user did not register or authenticate quickly enough
network_error There was a connection error between the client and SnapAuth
bad_request An invalid request was made. Usually this is a missing or invalid field
server_error Something went wrong our end. Please try again momentarily
canceled_by_user The user canceled the registration or authentication request
invalid_domain You are trying to perform a request on a domain that doesn't match the API key; OR you're trying to run on a non-HTTPS page
unexpected An unexpected error occurred. Please contact us for help!