Skip to main content
POST
/
auth
/
challenges
Create an authentication challenge
curl --request POST \
  --url https://api.guile.app/auth/challenges \
  --header 'Content-Type: application/json' \
  --data '
{
  "method": "otp",
  "phoneNumber": "<string>",
  "emailAddress": "<string>"
}
'
{
  "id": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z"
}

Body

application/json

The request body for issuing a new authentication challenge.

For OTP authentication, either phoneNumber or emailAddress is required. For passkey authentication, phoneNumber or emailAddress is optional (enables usernameless flow when omitted).

​
method
enum<string>
default:otp

The authentication method to use. Defaults to "otp" for backward compatibility.

Available options:
otp,
passkey
​
phoneNumber
string<phoneNumber>

The phone number of a user.

  • For OTP: Required (unless emailAddress is provided) to send the one-time passcode.
  • For passkey: Optional. When provided, enables username-first authentication flow.
Required string length: 6 - 32
Pattern: ^\+?[0-9]{1,3}?[ .-]?\(?[0-9]{1,4}?\)?[ .-]?[0-9]{1,4}?[ .-]?[0-9]{1,4}?[ .-]?[0-9]{1,9}$
​
emailAddress
string<emailAddress>

The email address of a user.

  • For OTP: Required (unless phoneNumber is provided) to send the one-time passcode.
  • For passkey: Optional. When provided, enables username-first authentication flow.
Required string length: 6 - 100

Response

Created.

Response from creating an authentication challenge.

The response type depends on the authentication method specified in the request:

  • For OTP method: Returns a Challenge with ID and expiration
  • For passkey method: Returns PasskeyAuthenticationOptions with WebAuthn challenge
​
id
string
required

The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.

​
expiresAt
string<date-time>
required

The expiration datetime of the challenge in the ISO-8601 format.