Skip to content

Update README w/ latest APIs #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 16, 2024
Merged

Update README w/ latest APIs #53

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5a81dc8
upgrade notes
Firehed Oct 16, 2024
e8471c3
Update README w/ latest terminlogy and params
Firehed Oct 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 15 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,9 @@ Browsers will ignore most WebAuthn requests that are not in response to a user g
### Registering a Credential

```typescript
// Get `name` from a field in your UI, your backend, etc.
// Get `username` from a field in your UI, your backend, etc.
// This should be what the user signs in with, such as a username or email address
const registration = await snapAuth.startRegister({ name })
const registration = await snapAuth.startRegister({ username })
if (registration.ok) {
const token = registration.data.token
// Send token to your backend to use the /credential/create API
Expand All @@ -78,19 +78,19 @@ if (registration.ok) {
> For security, the token expires in a few minutes.
> The response includes a `expiresAt` field indicating when this needs to be done.

The `name` value is used completely locally, and _is not sent to SnapAuth's servers_.
The `username` value is used completely locally, and _is not sent to SnapAuth's servers_.
This is should be a login handle such as a username or email address.

You may also set `displayName`, though browsers typically (counter-intuitively) ignore `displayName` in favor of `name`.
You may also set `displayName`, though browsers typically (counter-intuitively) ignore `displayName` in favor of `username`.

> [!WARNING]
> The `name` field cannot be changed at this time - it's not supported by browsers.
> The `username` field cannot be changed at this time - it's not supported by browsers.
> Once browser APIs exist to modify it, we will add support to the SDK.
> See [#40](https://github.com/snapauthapp/sdk-typescript/issues/40) for details.

#### Automatic Passkey Upgrades

Some browsers support automatic passkey upgrades (and others will be adding support soon).
Browsers and operating systems are adding support for [automatic passkey upgrades](/automatic-passkeys).
These allow adding passkeys to existing accounts without having to send the user through a separate UI flow.
If the browser supports it and the credential manager deems it appropriate, it will automatically create a passkey for the user.
See [the WWDC24 session video](https://developer.apple.com/videos/play/wwdc2024/10125/?time=38) for more information (automatic passkey upgrades are not Apple-specific).
Expand All @@ -100,9 +100,7 @@ Simply swap `startRegister` to `upgradeToPasskey`, and _avoid_ showing feedback
This should be called just _after_ the user signs in with a non-WebAuthn credential, such as a password or OTP code.

```typescript
// Name should, again, be a "handle" that the user uses to sign in (username,
// email, etc)
const registration = await snapAuth.upgradeToPasskey({ name })
const registration = await snapAuth.upgradeToPasskey({ username })
if (registration.ok) {
const token = registration.data.token
// Send token to your backend to use the /credential/create API
Expand All @@ -120,20 +118,20 @@ You can call our API in any browser!

```typescript
// This would typically be in an onClick/onSubmit handler
const handle = document.getElementById('username').value // Adjust to your UI
const auth = await snapAuth.startAuth({ handle })
const username = document.getElementById('username').value // Adjust to your UI
const auth = await snapAuth.startAuth({ username })
if (auth.ok) {
const token = auth.data.token
// Send token to your backend to use the /auth/verify API
// It will return the verified user's id and handle, which you should use to
// sign in the user with your existing mechanism (cookie, token, etc)
// It will return the verified user's id, which you should use to sign in the
// user with your existing mechanism (cookie, token, etc)
} else {
// Inspect auth.error and decide how best to proceed
}
```

You may use `id` or `handle` when calling `startAuth()`.
`id` is great when you already know who is signing in (returning user, MFA flows, etc); `handle` is more streamlined when initially authenticating.
You may use `id` or `username` when calling `startAuth()`.
`id` is great when you already know who is signing in (returning user, MFA flows, etc); `username` is more streamlined when initially authenticating.

Both values are **case-insensitive**.

Expand Down Expand Up @@ -174,8 +172,8 @@ const validateAuth = async (auth: AuthResponse) => {
}
}
const onSignInSubmit = async (e) => {
// get `handle` (commonly username or email) from a form field or similar
const auth = await snapAuth.startAuth({ handle })
// get `username` (commonly username or email) from a form field or similar
const auth = await snapAuth.startAuth({ username })
if (auth.ok) {
await validateAuth(auth)
} else {
Expand Down