{"id":35101267,"url":"https://github.com/snapauthapp/sdk-typescript","last_synced_at":"2026-04-27T14:03:02.295Z","repository":{"id":237527525,"uuid":"721844246","full_name":"snapauthapp/sdk-typescript","owner":"snapauthapp","description":"TypeScript/JavaScript SDK for SnapAuth","archived":false,"fork":false,"pushed_at":"2024-10-22T18:23:13.000Z","size":234,"stargazers_count":1,"open_issues_count":13,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-30T15:49:14.938Z","etag":null,"topics":["javascript","javascript-library","passkeys","snapauth","typescript","typescript-library","web-authentication","web-authentication-api","webauthn"],"latest_commit_sha":null,"homepage":"https://www.snapauth.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snapauthapp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-21T22:19:00.000Z","updated_at":"2024-10-22T18:22:09.000Z","dependencies_parsed_at":"2024-05-08T19:51:56.807Z","dependency_job_id":"ba9d5875-8d29-48af-8343-5043fa088041","html_url":"https://github.com/snapauthapp/sdk-typescript","commit_stats":null,"previous_names":["snapauthapp/sdk-typescript"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/snapauthapp/sdk-typescript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snapauthapp%2Fsdk-typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snapauthapp%2Fsdk-typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snapauthapp%2Fsdk-typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snapauthapp%2Fsdk-typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snapauthapp","download_url":"https://codeload.github.com/snapauthapp/sdk-typescript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snapauthapp%2Fsdk-typescript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32339290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","javascript-library","passkeys","snapauth","typescript","typescript-library","web-authentication","web-authentication-api","webauthn"],"created_at":"2025-12-27T16:58:15.591Z","updated_at":"2026-04-27T14:03:02.290Z","avatar_url":"https://github.com/snapauthapp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SnapAuth TypeScript/JavaScript SDK\n\nThis is the official TS/JS SDK for [SnapAuth](https://www.snapauth.app/?utm_source=GitHub\u0026utm_campaign=sdk\u0026utm_content=sdk-typescript).\n\nSnapAuth will let you add passkey support to your web (and native) app in a snap!\nAdd strong multi-factor authentication or go fully passwordless while maintaining a great, frictionless user experience.\n\nThis is for _client_ code.\nIf you're looking for the _server_ integration, check out [`@snapauth/node-sdk`](https://github.com/snapauthapp/sdk-node).\n\n[SnapAuth Homepage](https://www.snapauth.app?utm_source=GitHub\u0026utm_campaign=sdk\u0026utm_content=sdk-typescript)\n| [SnapAuth Docs](https://docs.snapauth.app)\n| [Dashboard](https://dashboard.snapauth.app)\n| [Github](https://github.com/snapauthapp/sdk-typescript)\n| [NPM](https://www.npmjs.com/package/@snapauth/sdk)\n\n[![GitHub Release](https://img.shields.io/github/v/release/snapauthapp/sdk-typescript)](https://github.com/snapauthapp/sdk-typescript/releases)\n[![Test](https://github.com/snapauthapp/sdk-typescript/actions/workflows/test.yml/badge.svg)](https://github.com/snapauthapp/sdk-typescript/actions/workflows/test.yml)\n![GitHub License](https://img.shields.io/github/license/snapauthapp/sdk-typescript)\n\n[![NPM Version](https://img.shields.io/npm/v/%40snapauth%2Fsdk)](https://www.npmjs.com/package/@snapauth/sdk)\n![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40snapauth%2Fsdk)\n![NPM Type Definitions](https://img.shields.io/npm/types/%40snapauth%2Fsdk)\n\n\n## Installation and Setup\n### Node\n```bash\nnpm i --save @snapauth/sdk\n```\nor\n```bash\nyarn add @snapauth/sdk\n```\n\n```typescript\nimport { SDK } from '@snapauth/sdk'\nconst snapAuth = new SDK('pubkey_your_value')\n```\n\n### Directly linking (UMD)\n```html\n\u003cscript src=\"https://unpkg.com/@snapauth/sdk@0.3.0/dist/index.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\"\u003e\nconst snapAuth = new SnapAuth.SDK('pubkey_your_value')\n\u003c/script\u003e\n```\n\n\u003e [!NOTE]\n\u003e Replace `pubkey_your_value` with the _publishable key_ for your domain from the [dashboard](https://dashboard.snapauth.app).\n\u003e Publishable keys are domain-specific and the domain MUST match what's in the browser's address bar.\n\n## Usage\nAll examples are in TypeScript.\nFor use with vanilla JavaScript, omit the type imports and annotations.\n\nThese should be run in response to a button click, form submission, etc.\nBrowsers will ignore most WebAuthn requests that are not in response to a user gesture.\n\n### Registering a Credential\n\n```typescript\n// Get `username` from a field in your UI, your backend, etc.\n// This should be what the user signs in with, such as a username or email address\nconst registration = await snapAuth.startRegister({ username })\nif (registration.ok) {\n  const token = registration.data.token\n  // Send token to your backend to use the /credential/create API\n} else {\n  // Inspect registration.error and decide how best to proceed\n}\n```\n\n\u003e [!IMPORTANT]\n\u003e You MUST send the token to the backend [`/credential/create`](https://docs.snapauth.app/server.html#create-a-credential) API to associate it with the user.\n\u003e Until this is done, the user will not be able to use their new credential.\n\u003e\n\u003e For security, the token expires in a few minutes.\n\u003e The response includes a `expiresAt` field indicating when this needs to be done.\n\nThe `username` value is used completely locally, and _is not sent to SnapAuth's servers_.\nThis is should be a login handle such as a username or email address.\n\nYou may also set `displayName`, though browsers typically (counter-intuitively) ignore `displayName` in favor of `username`.\n\n\u003e [!WARNING]\n\u003e The `username` field cannot be changed at this time - it's not supported by browsers.\n\u003e Once browser APIs exist to modify it, we will add support to the SDK.\n\u003e See [#40](https://github.com/snapauthapp/sdk-typescript/issues/40) for details.\n\n#### Automatic Passkey Upgrades\n\nBrowsers and operating systems are adding support for [automatic passkey upgrades](/automatic-passkeys).\nThese allow adding passkeys to existing accounts without having to send the user through a separate UI flow.\nIf the browser supports it and the credential manager deems it appropriate, it will automatically create a passkey for the user.\nSee [the WWDC24 session video](https://developer.apple.com/videos/play/wwdc2024/10125/?time=38) for more information (automatic passkey upgrades are not Apple-specific).\n\nTo do this with SnapAuth, it's very similar to registration process above.\nSimply swap `startRegister` to `upgradeToPasskey`, and _avoid_ showing feedback to users on failures.\nThis should be called just _after_ the user signs in with a non-WebAuthn credential, such as a password or OTP code.\n\n```typescript\nconst registration = await snapAuth.upgradeToPasskey({ username })\nif (registration.ok) {\n  const token = registration.data.token\n  // Send token to your backend to use the /credential/create API\n} else {\n  // You may want to log this error or add metrics, but should NOT display\n  // anything to the user in this flow.\n}\n```\n\nSnapAuth will automatically handle browser support detection, and return an `api_unsupported_in_browser` for browsers that do not support automatic upgrades.\nYou can call our API in any browser!\n\n\n### Authenticating\n\n```typescript\n// This would typically be in an onClick/onSubmit handler\nconst username = document.getElementById('username').value // Adjust to your UI\nconst auth = await snapAuth.startAuth({ username })\nif (auth.ok) {\n  const token = auth.data.token\n  // Send token to your backend to use the /auth/verify API\n  // It will return the verified user's id, which you should use to sign in the\n  // user with your existing mechanism (cookie, token, etc)\n} else {\n  // Inspect auth.error and decide how best to proceed\n}\n```\n\nYou may use `id` or `username` when calling `startAuth()`.\n`id` is great when you already know who is signing in (returning user, MFA flows, etc); `username` is more streamlined when initially authenticating.\n\nBoth values are **case-insensitive**.\n\n\u003e [!CAUTION]\n\u003e DO NOT sign in the user based on getting the client token alone!\n\u003e You MUST send it to the [`/auth/verify`](https://docs.snapauth.app/server.html#verify-authentication-token) Server API endpoint, and inspect its response to get the _verified_ user id to securely authenticate.\n\n#### AutoFill-assisted requests\n\nMost browsers support credential autofill, which will automatically prompt a user to sign in using a previously-registered credential.\nTo take advantage of this, you need two things:\n\n1) An `\u003cinput\u003e` (or `\u003ctextarea\u003e`) field with `autocomplete=\"username webauthn\"` set[^1].\n   We strongly recommend adding these details to your standard sign-in field:\n```html\n\u003cinput type=\"text\" autocomplete=\"username webauthn\" placeholder=\"Username\" /\u003e\n```\n\n2) Run the `autofill` API.\n   This returns an `AuthResponse`, just like the modal `startAuth()` method.\n```typescript\nconst auth = await snapAuth.autofill()\n```\n\nUnlike the direct startRegister and startAuth calls, autofill CAN and SHOULD be called as early in the page lifecycle is possible (_not_ in response to a user gesture).\nThis helps ensure that autofill can occur when a user interacts with the form field.\n\n\u003e [!TIP]\n\u003e Use the same logic to validate the the response from both `autofill()` and `startAuth()`.\n\u003e\n\u003e Avoid giving the user visual feedback if autofill returns an error.\n\n```typescript\nimport { AuthResponse } from '@snapauth/sdk'\nconst validateAuth = async (auth: AuthResponse) =\u003e {\n  if (auth.ok) {\n    await fetch(...) // send auth.data.token to your backend to sign in the user\n  }\n}\nconst onSignInSubmit = async (e) =\u003e {\n  // get `username` (commonly username or email) from a form field or similar\n  const auth = await snapAuth.startAuth({ username })\n  if (auth.ok) {\n      await validateAuth(auth)\n    } else {\n      // Display a message to the user, send to a different flow, etc.\n    }\n}\n\nconst afAuth = await snapauth.autofill()\nif (afAuth.ok) {\n    validateAuth(afAuth)\n}\n```\n\n## Building the SDK\n\nRun `npm run watch` to keep the build running continually on file change.\n\nTo make the local version available for linking, run `npm link` in this directory.\n\nIn the project that should _use_ the local version, run `npm link '@snapauth/sdk'` which will set up the symlinking.\n\nIf working with a non-production backend, provide the host as a string to the second parameter of the SDK constructor.\n\n[^1]: The WebAuthn spec says that only `webauthn` is required in `autocomplete`, but real-world browser testing shows that using exactly `autocomplete=\"username webauthn\"` string is most reliable.\nIf you do not have this element, or the browser otherwise fails to detect it, the autofill-assited experience will not start.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnapauthapp%2Fsdk-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnapauthapp%2Fsdk-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnapauthapp%2Fsdk-typescript/lists"}