Skip to main content
The Authentication API handles user authentication through challenge-based verification using one-time passcodes sent via email or SMS. Once verified, users receive JWT tokens to access protected resources throughout the platform.

​
How Authentication Works

Authentication on Guile follows a challenge-response pattern. When a user wants to sign in, they request a challenge for their email address or phone number. The system sends them a one-time passcode, which they submit back to receive access tokens. Access tokens are short-lived (15 minutes) and 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.

​
Token Management

The platform uses two types of tokens. Access tokens authenticate your API requests and expire quickly for security. Refresh tokens last much longer and let you get new access tokens without re-authenticating the user. If a refresh token becomes invalid or expires, the API returns an invalidRefreshToken error, and you’ll need to start the authentication flow over.

​
Challenge Methods

You can authenticate users through their email address or phone number, but not both in the same request. The API enforces this with a mutuallyExclusiveSearchCriteria error if you try to specify both. Rate limiting protects against abuse, so authentication requests may be throttled if too many are made in a short period.