Skip to main content
The Authentication API provides multiple authentication methods to suit different use cases and security requirements. Users can authenticate via one-time passcodes (OTP) sent via email or SMS, or use passkeys for secure, passwordless authentication. Once verified, users receive JWT tokens to access protected resources throughout the platform.

​
Authentication Methods

Guile supports two authentication methods through a unified challenge-based API:

​
One-Time Passcode (OTP)

Traditional authentication where users receive a code via email or SMS. Best for:
  • First-time users without passkeys
  • Users on devices without biometric capabilities
  • Fallback when passkey authentication fails

​
Passkey Authentication

Modern, passwordless authentication using WebAuthn. Best for:
  • Returning users with registered passkeys
  • Enhanced security requirements
  • Improved user experience with biometrics
Both methods use the same unified endpoints with a method parameter to specify the authentication type.

​
How Authentication Works

Authentication on Guile follows a unified challenge-response pattern:

​
OTP Flow

​
Passkey Flow

​
Unified Challenge API

The platform provides a unified challenge creation endpoint that supports both authentication methods: Create Challenge: POST /auth/challenges
  • For OTP: Include phoneNumber or emailAddress (required)
  • For Passkey: Optionally include phoneNumber or emailAddress for username-first flow
Verify Authentication: POST /auth/verifiedChallenges
  • For OTP: Include challengeId and code
  • For Passkey: Include assertion
Both methods return the same token structure upon successful verification.

​
Token Management

The platform uses two types of tokens. Access tokens authenticate your API requests and expire quickly for security (15 minutes). Refresh tokens last much longer and let you get new access tokens without re-authenticating the user. Access tokens must be included in the Authorization header for protected API calls. When they expire, you can exchange your refresh token for new tokens without going through the challenge flow again. For operations that don’t require user authentication, you can issue an anonymous token instead. If a refresh token becomes invalid or expires, the API returns an invalidRefreshToken error, and you’ll need to start the authentication flow over.

​
Best Practices

  1. Offer both methods: Support both OTP and passkey authentication for maximum compatibility
  2. Passkey-first: Present passkey authentication as the primary option for returning users
  3. Graceful fallback: Always provide OTP as a backup authentication method
  4. Rate limiting: Be aware that authentication requests may be throttled if too many are made in a short period