Authentication overview

Use the Authentication API to prove who is calling. You challenge with a one-time passcode (email or SMS) or a passkey, then you get JWT access and refresh tokens for protected calls.

​

What you do first

1. Pick a method: passkey when the person already registered one; OTP when they have no passkey, biometrics fail, or you need a fallback.
2. Create an authentication challenge with method set to otp or passkey.
3. Verify authentication with the OTP code or passkey assertion.
4. Put the access token in the Authorization header. When it expires, exchange the refresh token.

For a first-time customer, issue a phone OTP before they have a Guile account, verify customer registration, then complete customer registration with profile fields. Returning users still get tokens from verify authentication. For calls that do not need a signed-in person, issue an anonymous token. After a barber signs in, call get authenticated session context for the barber and business ids. Do not decode token claims for those ids.

​

States that matter

If the refresh token is invalid or expired, you get Invalid Refresh Token and must run the challenge flow again.

​

When a call fails

Failures come back as problem documents. Open the type link for the cause, the fix, and whether retrying is safe. Common ones on this path:

• Challenge Expired: create a new challenge
• Invalid Refresh Token: sign in again
• Invalid Passkey Assertion: fall back to OTP
• Registration Session Consumed: replay the identical complete call, or start a new session for a new account
• Too Many Requests: wait for the rate limit

​

Related paths

• Passkeys: register and manage WebAuthn credentials
• Idempotency keys: registration and other writes that accept a key
• Problem types: how to read a failure