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

# Initiate Challenge

> Initiate a challenge by sending a verification code to an  email address or phone number.



## OpenAPI

````yaml server-api POST /challenge
openapi: 3.0.0
info:
  description: Authsignal's Server API.
  version: 1.0.0
  title: Server API
  termsOfService: https://www.authsignal.com/legal/terms-of-service
  contact:
    email: hello@authsignal.com
servers:
  - url: https://api.authsignal.com/v1
  - url: https://au.api.authsignal.com/v1
  - url: https://eu.api.authsignal.com/v1
  - url: https://ca.api.authsignal.com/v1
security:
  - basicAuth: []
tags:
  - name: users
    description: ''
    externalDocs:
      description: Find out more
      url: https://docs.authsignal.com
  - name: challenge
    description: ''
    externalDocs:
      description: Find out more
      url: https://docs.authsignal.com
  - name: authenticator configurations
    description: ''
    externalDocs:
      description: Find out more
      url: https://docs.authsignal.com
  - name: actions
    description: ''
    externalDocs:
      description: Find out more
      url: https://docs.authsignal.com
  - name: query
    description: ''
    externalDocs:
      description: Find out more
      url: https://docs.authsignal.com
  - name: email
    description: ''
    externalDocs:
      description: Find out more
      url: https://docs.authsignal.com
  - name: sms
    description: ''
    externalDocs:
      description: Find out more
      url: https://docs.authsignal.com
  - name: verify
    description: ''
    externalDocs:
      description: Find out more
      url: https://docs.authsignal.com
  - name: challenges
    description: ''
    externalDocs:
      description: Find out more
      url: https://docs.authsignal.com
  - name: sessions
    description: ''
    externalDocs:
      description: Find out more
      url: https://docs.authsignal.com
  - name: devices
    description: ''
    externalDocs:
      description: Find out more
      url: https://docs.authsignal.com
externalDocs:
  description: Find out more about Authsignal
  url: https://docs.authsignal.com
paths:
  /challenge:
    post:
      tags:
        - challenge
        - sms
        - email
      summary: Initiate challenge
      description: >-
        Initiate a challenge by sending a verification code to an  email address
        or phone number.
      operationId: initiateChallenge
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                verificationMethod:
                  enum:
                    - EMAIL_OTP
                    - SMS
                    - WHATSAPP
                  description: The verification method to use for the challenge.
                action:
                  type: string
                  description: >-
                    The action code used to identify the challenge in the
                    Authsignal Portal.
                idempotencyKey:
                  type: string
                  description: >-
                    The idempotency key for the action. An idempotency key can
                    be used to initiate multiple challenges for the same action.
                phoneNumber:
                  type: string
                  description: >-
                    The phone number in E.164 format. Required if the
                    verification method is 'SMS'.
                email:
                  type: string
                  description: >-
                    The email address. Required if the verification method is
                    'EMAIL_OTP'.
                userId:
                  type: string
                  description: >-
                    The primary ID of the user in your system. Required when
                    initiating a challenge to enroll or update an authenticator
                    for an existing user.
                scope:
                  type: string
                  enum:
                    - add:authenticators
                    - update:authenticators
                    - add:authenticators update:authenticators
                  description: >-
                    Providing scopes will authorize enrolling or updating an
                    authenticator for an existing user. Must only be provided
                    when initiating a challenge from an already authenticated
                    state.
                locale:
                  $ref: '#/components/schemas/Locale'
                ipAddress:
                  type: string
                  description: >-
                    The user's IP address. Can be provided to use rules based on
                    location or other IP-derived features.
                userAgent:
                  type: string
                  description: >-
                    The user agent identifying a browser or app. Can be provided
                    to use rules based on device.
                deviceId:
                  type: string
                  description: >-
                    An ID which identifies the user's device. Can be provided to
                    use rules based on device.
                custom:
                  type: object
                  description: >-
                    A JSON object which can include any key/value pairs. Can be
                    provided to use rules based on your own data points.
              required:
                - verificationMethod
                - action
            example:
              verificationMethod: SMS
              action: signInWithSms
              phoneNumber: '+64270000000'
              locale: en
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  challengeId:
                    type: string
                    description: The ID of the challenge.
                  idempotencyKey:
                    type: string
                    description: >-
                      The idempotency key for the action. An idempotency key can
                      be used to initiate multiple challenges for the same
                      action.
                  expiresAt:
                    type: number
                    description: The challenge expiry as a Unix timestamp in seconds.
                required:
                  - challengeId
                  - idempotencyKey
                  - expiresAt
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Locale:
      type: string
      description: >-
        The locale of the user in BCP 47 format. Used to localize the pre-built
        UI, email, and SMS messages.
      pattern: ^[a-z]{2}(-[a-zA-Z]{2,})?$
      example: es
    Error:
      type: object
      properties:
        error:
          type: string
        errorDescription:
          type: string
      required:
        - error
  responses:
    InvalidRequest:
      description: Invalid Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Use your Authsignal Server API secret key as the username and leave the
        password empty. The secret key can be found in the API Keys section of
        the Authsignal Portal settings page.

````