> ## 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. # Start Flow > Start an Authsignal flow for a given action and, optionally, a known user. ## OpenAPI ````yaml server-api POST /flows 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 - url: https://uk.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 - name: flows description: '' externalDocs: description: Find out more url: https://docs.authsignal.com externalDocs: description: Find out more about Authsignal url: https://docs.authsignal.com paths: /flows: post: tags: - flows summary: Start flow description: >- Start an Authsignal flow for a given action and, optionally, a known user. operationId: startFlow requestBody: content: application/json: schema: type: object properties: actionCode: type: string description: >- A short human-readable code which defines the action that the user is performing, e.g. `signIn`. This must match the value that you entered when creating the flow in the Authsignal Portal. user: $ref: '#/components/schemas/FlowUserLookup' attributes: $ref: '#/components/schemas/FlowChallengeAttributes' redirectUrl: type: string description: >- Where Authsignal redirects the user after they complete the flow via the pre-built UI. Only required if using the pre-built UI in redirect mode. clientId: type: string description: >- The ID of the app client configured in the Authsignal Portal. Required if you're using Authsignal's session management to issue access tokens or refresh tokens. required: - actionCode example: actionCode: signIn user: userId: eb734046-d25d-4cf8-8faa-26a519864121 responses: '200': description: OK content: application/json: schema: type: object properties: action: $ref: '#/components/schemas/FlowAction' challengeToken: type: string description: >- A token which can be used if integrating using client SDKs. Whenever a verification or enrollment step in a flow is completed, the old challenge token will be invalidated and a new challenge token issued. Always send the latest challenge token in your requests. challengeUrl: type: string description: >- A URL which can be used to launch this flow instance in the pre-built UI. user: $ref: '#/components/schemas/FlowUser' required: - action - challengeToken - challengeUrl '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' components: schemas: FlowUserLookup: type: object description: >- An identifier used to lookup a user. Provide exactly one of userId, email, phoneNumber, or username. If no user exists in Authsignal for the provided identifier then a record will be created. properties: userId: type: string description: The primary ID of the user in your system. email: type: string description: The user's email address. phoneNumber: type: string description: The user's phone number, in E.164 format. username: type: string description: The user's username. FlowChallengeAttributes: type: object properties: 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. locale: $ref: '#/components/schemas/Locale' 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. FlowAction: type: object properties: state: $ref: '#/components/schemas/FlowState' completedSteps: type: array items: $ref: '#/components/schemas/FlowCompletedActionStep' description: Steps already completed in this flow. nextStep: allOf: - $ref: '#/components/schemas/FlowActionStep' description: >- The next step in the flow which must be completed. Absent if there are no more steps. required: - state - completedSteps FlowUser: type: object properties: userId: type: string email: type: string phoneNumber: type: string username: type: string displayName: type: string authenticators: type: array items: $ref: '#/components/schemas/FlowUserAuthenticator' required: - userId - authenticators 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 FlowState: type: string enum: - CHALLENGE_REQUIRED - CHALLENGE_SUCCEEDED - CHALLENGE_FAILED description: >- The current state of the flow. Indicates whether the flow has succeeded, failed, or is still awaiting a challenge. FlowCompletedActionStep: type: object properties: stepType: $ref: '#/components/schemas/FlowActionStepType' verificationMethod: $ref: '#/components/schemas/VerificationMethod' userAuthenticatorId: type: string description: The ID of the authenticator used to complete this step. required: - stepType - verificationMethod - userAuthenticatorId FlowActionStep: type: object properties: stepType: $ref: '#/components/schemas/FlowActionStepType' verificationMethods: type: array items: $ref: '#/components/schemas/FlowVerificationMethod' description: >- The verification methods that can be used to complete this step. Flows only currently support a subset of verification methods. required: - stepType - verificationMethods FlowUserAuthenticator: type: object properties: userAuthenticatorId: type: string verificationMethod: $ref: '#/components/schemas/FlowVerificationMethod' email: type: string phoneNumber: type: string username: type: string displayName: type: string required: - userAuthenticatorId - verificationMethod Error: type: object properties: error: type: string errorDescription: type: string required: - error FlowActionStepType: type: string enum: - VERIFICATION_REQUIRED - ENROLLMENT_REQUIRED - ENROLLMENT_OPTIONAL description: >- Whether the next step requires the user to verify with an existing authenticator, or enroll a new one. VerificationMethod: type: string enum: - SMS - AUTHENTICATOR_APP - EMAIL_MAGIC_LINK - EMAIL_OTP - PUSH - DEVICE - SECURITY_KEY - PASSKEY - VERIFF - IPROOV - PALM_BIOMETRICS_RR - IDVERSE - WHATSAPP FlowVerificationMethod: type: string enum: - AUTHENTICATOR_APP - EMAIL_OTP - PASSKEY - SMS - WHATSAPP 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. ````