> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guile.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an authentication challenge

> Issue an authentication challenge. Phone challenges may be issued for
registered or unregistered phone numbers. Email challenges are delivered
only to the email address already registered to an account. Unknown email
addresses, locked accounts, and throttled registered accounts receive the
same public response without revealing delivery or account state. A
successful email OTP verifies the registered email address.
Requests may also be limited by the shared user resend policy or the
caller IP. A 429 response includes Retry-After when exposing the wait
does not reveal account state.



## OpenAPI

````yaml /api-reference/Authentication/openapi.yaml post /auth/challenges
openapi: 3.0.0
info:
  title: Authentication
  version: 0.1.0
  contact:
    name: Guile Engineering
    url: https://www.guile.app
    email: engineering@guile.app
  license:
    name: MIT
    url: https://opensource.org/license/mit
  description: >-
    The Authentication API provides operations which create and verify

    authentication challenges for users. Upon verification, users are issued

    an access token to use for protected API operations. Additionally,

    users are issued an offline refresh token. The refresh token is used in

    exchange for a new access token without challenge verification. Access

    tokens are short lived, typically valid for only 15 minutes. Access and

    refresh tokens may be revoked if they are determined to have been
    compromised.
servers:
  - url: https://api.guile.app
    variables: {}
  - url: https://guile.fly.dev
    variables: {}
security: []
tags:
  - name: Passkeys
    description: Register and manage passkeys
  - name: Token management
    description: Issue, refresh, and revoke access tokens
  - name: Email verification
    description: Prove ownership of an email on an authenticated account
  - name: Registration
    description: Register a new customer account
  - name: Challenges
    description: Start and complete sign-in challenges
paths:
  /auth/challenges:
    post:
      tags:
        - Challenges
      summary: Create an authentication challenge
      description: >-
        Issue an authentication challenge. Phone challenges may be issued for

        registered or unregistered phone numbers. Email challenges are delivered

        only to the email address already registered to an account. Unknown
        email

        addresses, locked accounts, and throttled registered accounts receive
        the

        same public response without revealing delivery or account state. A

        successful email OTP verifies the registered email address.

        Requests may also be limited by the shared user resend policy or the

        caller IP. A 429 response includes Retry-After when exposing the wait

        does not reveal account state.
      operationId: createAuthenticationChallenge
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/newChallenge'
            examples:
              example0:
                value:
                  method: otp
                  phoneNumber: '+12125550100'
              example1:
                value:
                  method: otp
              example2:
                value:
                  method: otp
                  phoneNumber: '+12125550100'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/challengeResponse'
              example:
                id: 0190f0c0-aaaa-7aaa-8aaa-aaaaaaaaaaaa
                expiresAt: '2026-08-01T16:00:00.000Z'
        '400':
          description: >-
            Bad Request.

            The request body, request headers, and/or query parameters are not
            well-formed.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/badRequest](https://docs.guile.app/problems/badRequest)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
              example:
                id: 0190f0c0-cccc-7ccc-8ccc-cccccccccccc
                type: https://docs.guile.app/problems/badRequest
                title: Bad Request
                status: 400
                detail: Provide a phone number or email for OTP delivery.
                occurredAt: '2026-08-01T16:00:00.000Z'
        '401':
          description: >-
            Unauthorized.

            The operation requires authentication but no authentication or
            insufficient authentication was given.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/unauthorized](https://docs.guile.app/problems/unauthorized)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '403':
          description: >-
            Forbidden.

            The authenticated caller is not authorized to perform the requested
            operation.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '422':
          description: >-
            Unprocessable Entity.

            The request body and/or query parameters were well-formed but
            otherwise invalid.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/unprocessableEntity](https://docs.guile.app/problems/unprocessableEntity)

            *
            [https://docs.guile.app/problems/mutuallyExclusiveChallengeMethods](https://docs.guile.app/problems/mutuallyExclusiveChallengeMethods)

            *
            [https://docs.guile.app/problems/challengeTimeIntervalNotExceeded](https://docs.guile.app/problems/challengeTimeIntervalNotExceeded)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '429':
          description: >-
            Too Many Requests.

            The client has sent too many requests in a given amount of time.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/tooManyRequests](https://docs.guile.app/problems/tooManyRequests)
          headers:
            Retry-After:
              required: true
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
                format: uint32
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
              example:
                id: 0190f0c0-cccc-7ccc-8ccc-cccccccccccc
                type: https://docs.guile.app/problems/tooManyRequests
                title: Too Many Requests
                status: 429
                detail: Wait before requesting another verification code.
                occurredAt: '2026-08-01T16:00:00.000Z'
                recovery:
                  outcome: notApplied
                  retry: retrySameRequestAfterDelay
                  rateLimit:
                    limit: 5
                    remaining: 4
                    resetsAt: '2026-08-01T17:00:00.000Z'
components:
  schemas:
    newChallenge:
      type: object
      properties:
        method:
          allOf:
            - $ref: '#/components/schemas/authenticationMethod'
          description: |-
            The authentication method to use.
            Defaults to "otp" for backward compatibility.
          default: otp
        phoneNumber:
          allOf:
            - $ref: '#/components/schemas/phoneNumber'
          description: >-
            Phone number used for OTP delivery or username-first passkey
            authentication.

            Required for OTP unless emailAddress is provided; optional for
            passkey.
        emailAddress:
          allOf:
            - $ref: '#/components/schemas/emailAddress'
          description: >-
            Email address used for OTP delivery or username-first passkey
            authentication.

            Required for OTP unless phoneNumber is provided; optional for
            passkey.
      description: >-
        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).
    challengeResponse:
      anyOf:
        - $ref: '#/components/schemas/challenge'
        - $ref: '#/components/schemas/passkeyAuthenticationOptions'
      description: >-
        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.
    apiProblem:
      type: object
      required:
        - type
        - title
        - occurredAt
        - id
        - status
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/uri'
          description: A URI reference that identifies the problem type.
        title:
          type: string
          maxLength: 120
          description: >-
            A short, human-readable summary of the problem type. The title is
            usually the same for all

            problems with the same `type`.
        occurredAt:
          type: string
          format: date-time
          description: >-
            The date-time when this problem occurred, in [RFC
            3339](https://tools.ietf.org/html/rfc3339)

            date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived
            and immutable.
        detail:
          type: string
          maxLength: 256
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: >-
            The unique identifier for this problem. This is an immutable opaque
            string.
        status:
          allOf:
            - $ref: '#/components/schemas/statusCode'
          description: >-
            The [HTTP status
            code](https://datatracker.ietf.org/doc/html/rfc7231#section-6)for
            this

            occurrence of the problem.
        instance:
          allOf:
            - $ref: '#/components/schemas/uri'
          maxLength: 2048
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem. This is the URI of an

            API resource that the problem is related to, with a unique error
            correlation ID URI fragment.
        attributes:
          type: object
          additionalProperties: {}
          description: >-
            Additional optional attributes related to the problem. This data
            conforms to the schema

            associated with the error type.
        recovery:
          allOf:
            - $ref: '#/components/schemas/clientFailureRecovery'
          description: The recovery contract for this problem occurrence.
        problems:
          type: array
          items:
            $ref: '#/components/schemas/problem'
          maxItems: 128
          description: |-
            Optional root-causes if there are multiple problems in the request
            or API call processing.
      description: >-
        API problem or error response, as per

        [RFC 9457
        application/problem+json](https://tools.ietf.org/html/rfc9457).
    authenticationMethod:
      type: string
      enum:
        - otp
        - passkey
      description: Authentication methods supported by the platform.
    phoneNumber:
      type: string
      minLength: 6
      maxLength: 32
      pattern: >-
        ^\+?[0-9]{1,3}?[ .-]?\(?[0-9]{1,4}?\)?[ .-]?[0-9]{1,4}?[
        .-]?[0-9]{1,4}?[ .-]?[0-9]{1,9}$
      format: phoneNumber
      description: A phone number.
    emailAddress:
      type: string
      minLength: 6
      maxLength: 100
      format: emailAddress
      description: An email address.
    challenge:
      type: object
      required:
        - id
        - expiresAt
      properties:
        id:
          $ref: '#/components/schemas/resourceId'
        expiresAt:
          type: string
          format: date-time
          description: |-
            The expiration datetime of the challenge in the ISO-8601
            format.
      description: The JSON representation of an authentication challenge.
    passkeyAuthenticationOptions:
      type: object
      required:
        - challenge
        - relyingPartyId
        - allowCredentials
        - userVerification
      properties:
        challenge:
          type: string
          description: |-
            The challenge for the authentication ceremony.
            This is a base64url-encoded random value.
        timeout:
          type: integer
          format: int32
          description: The timeout for the authentication ceremony in milliseconds.
          example: 60000
        relyingPartyId:
          type: string
          description: The relying party identifier.
          example: guile.app
        allowCredentials:
          type: array
          items:
            $ref: '#/components/schemas/allowedCredential'
          description: |-
            List of acceptable credentials for username-first authentication.
            Empty for usernameless authentication to allow credential discovery.
        userVerification:
          allOf:
            - $ref: '#/components/schemas/userVerificationRequirement'
          description: User verification requirement.
      description: |-
        WebAuthn authentication options for passkey sign-in.

        Supports both username-first and usernameless authentication flows.
    uri:
      type: string
      maxLength: 1024
      format: uri
      description: A URI reference to an internal or external resource.
    resourceId:
      type: string
      description: >-
        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.
    statusCode:
      type: integer
      format: uint16
      minimum: 100
      maximum: 599
      description: The HTTP status code for a response.
    clientFailureRecovery:
      type: object
      required:
        - outcome
        - retry
      properties:
        outcome:
          allOf:
            - $ref: '#/components/schemas/clientFailureOutcome'
          description: The known outcome of the request.
        retry:
          allOf:
            - $ref: '#/components/schemas/clientRetryDirective'
          description: The safe retry action for the request.
        sessionAction:
          allOf:
            - $ref: '#/components/schemas/clientSessionAction'
          description: The session action required before the request can continue.
        rateLimit:
          allOf:
            - $ref: '#/components/schemas/rateLimit'
          description: The rate limit state that prevented the request.
      description: The recovery contract for a failed client request.
    problem:
      type: object
      required:
        - type
        - title
        - occurredAt
        - id
        - status
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/uri'
          description: A URI reference that identifies the problem type.
        title:
          type: string
          maxLength: 120
          description: >-
            A short, human-readable summary of the problem type. The title is
            usually the same for all

            problems with the same `type`.
        occurredAt:
          type: string
          format: date-time
          description: >-
            The date-time when this problem occurred, in [RFC
            3339](https://tools.ietf.org/html/rfc3339)

            date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived
            and immutable.
        detail:
          type: string
          maxLength: 256
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: >-
            The unique identifier for this problem. This is an immutable opaque
            string.
        status:
          allOf:
            - $ref: '#/components/schemas/statusCode'
          description: >-
            The [HTTP status
            code](https://datatracker.ietf.org/doc/html/rfc7231#section-6)for
            this

            occurrence of the problem.
        instance:
          allOf:
            - $ref: '#/components/schemas/uri'
          maxLength: 2048
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem. This is the URI of an

            API resource that the problem is related to, with a unique error
            correlation ID URI fragment.
        attributes:
          type: object
          additionalProperties: {}
          description: >-
            Additional optional attributes related to the problem. This data
            conforms to the schema

            associated with the error type.
      description: >-
        Standard problem or error response, as per

        [RFC 9457
        application/problem+json](https://tools.ietf.org/html/rfc9457).
    allowedCredential:
      type: object
      required:
        - type
        - id
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/publicKeyCredentialType'
          description: The type of credential.
        id:
          type: string
          description: The credential ID as a base64url-encoded string.
        transports:
          type: array
          items:
            $ref: '#/components/schemas/authenticatorTransport'
          description: Acceptable transports for this credential.
      description: An allowed credential for WebAuthn authentication.
    userVerificationRequirement:
      type: string
      enum:
        - required
        - preferred
        - discouraged
      description: User verification requirement for WebAuthn.
    clientFailureOutcome:
      type: string
      enum:
        - notApplied
        - unknown
      description: The known outcome of a failed client request.
    clientRetryDirective:
      type: string
      enum:
        - doNotRetry
        - retrySameRequest
        - retrySameRequestAfterDelay
      description: The safe retry action for a failed client request.
    clientSessionAction:
      type: string
      enum:
        - refresh
        - signIn
      description: The session action required before a failed request can continue.
    rateLimit:
      type: object
      required:
        - limit
        - remaining
        - resetsAt
      properties:
        limit:
          type: integer
          format: uint64
          description: The maximum number of requests allowed in the active window.
        remaining:
          type: integer
          format: uint64
          description: The number of requests remaining in the active window.
        resetsAt:
          type: string
          format: date-time
          description: >-
            The date-time when the active window resets, in [RFC
            3339](https://tools.ietf.org/html/rfc3339) date-time
            `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC.
      description: The rate limit state for the request.
    publicKeyCredentialType:
      type: string
      enum:
        - public-key
      description: The type of public key credential.
    authenticatorTransport:
      type: string
      enum:
        - usb
        - nfc
        - ble
        - internal
        - hybrid
      description: Authenticator transport methods for WebAuthn.

````