> ## 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. # Track Action > Record authentication events performed by users and initiate challenges via Authsignal's pre-built UI or Authsignal Client SDKs. ## OpenAPI ````yaml server-api POST /users/{userId}/actions/{action} 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: /users/{userId}/actions/{action}: post: tags: - users summary: Track action description: >- Record authentication events performed by users and initiate challenges via Authsignal's pre-built UI or Authsignal Client SDKs. operationId: createAction parameters: - $ref: '#/components/parameters/userId' - $ref: '#/components/parameters/action' requestBody: required: true content: application/json: schema: type: object properties: redirectUrl: type: string description: >- The URL which the pre-built UI will redirect back to after the user exits Authsignal's pre-built UI. Only required when using the pre-built UI in redirect mode. redirectToSettings: type: boolean description: >- If set to true, the user will be shown the authentication settings screen after completing a challenge. Use this flag to allow users to manage their own authenticators through Authsignal's pre-built UI. email: type: string description: The user's email address. phoneNumber: type: string description: The user's phone number in E.164 format. ipAddress: type: string description: >- The user's IP address. Should be provided when using rules based on location or other IP-derived features. userAgent: type: string description: >- The user agent identifying a browser or app. Should be provided when using rules based on device. deviceId: type: string description: >- An ID which identifies the user's device. Should be provided when using rules based on device. scope: type: string description: >- The scopes granted to the pre-built UI and the token which can be passed to Client SDKs. By default the only scope is `read:authenticators`. custom: type: object description: >- A JSON object which can include any key/value pairs. Should be provided when using rules based on custom data points from your own app. locale: $ref: '#/components/schemas/Locale' crypto: $ref: '#/components/schemas/Crypto' customDomain: type: string description: >- The custom domain to use for the pre-built UI. If not provided, the default domain will be used. example: redirectUrl: https://yourapp.com/callback responses: '200': description: OK content: application/json: schema: type: object properties: state: $ref: '#/components/schemas/ActionState' url: type: string description: >- The URL for initiating a challenge using Authsignal's pre-built UI. You can redirect to this URL if the state determines that a challenge is required, or if you want to allow the user to enroll or to manage their existing authenticator settings. token: type: string description: >- A short-lived token which can be passed to Authsignal's Client SDKs (e.g. when using passkeys) or to authenticate to Authsignal's client API. isEnrolled: type: boolean description: >- True if the user is enrolled with at least one verification method and can be challenged. idempotencyKey: type: string description: >- A unique key which identifies a particular action. This key can be used to determine if the user has successfully completed a challenge. allowedVerificationMethods: type: array items: $ref: '#/components/schemas/VerificationMethod' description: >- The list of verification methods which the user is permitted to enroll. enrolledVerificationMethods: type: array items: $ref: '#/components/schemas/VerificationMethod' description: >- The list of verification methods which the user has enrolled. defaultVerificationMethod: $ref: '#/components/schemas/VerificationMethod' ruleIds: type: array items: type: string description: The IDs of the triggered rules. '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: userId: name: userId in: path description: The ID of the user. required: true schema: type: string action: name: action in: path description: >- A short human-readable code which defines the action that the user is performing, e.g. `signIn`. This value will be displayed in the Authsignal Portal and can be used to configure rules for authentication events with differing risk profiles. Values are validated with the following regex: `^[a-zA-Z0-9_-]{(1, 64)}$`. required: true schema: type: string 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 Crypto: type: object properties: asset: type: string address: type: string txnHash: type: string assetAmount: type: number assetAmountUsd: type: number ActionState: type: string enum: - ALLOW - BLOCK - CHALLENGE_REQUIRED - CHALLENGE_FAILED - CHALLENGE_SUCCEEDED - REVIEW_REQUIRED - REVIEW_FAILED - REVIEW_SUCCEEDED description: The current state of the action. VerificationMethod: type: string enum: - SMS - AUTHENTICATOR_APP - EMAIL_MAGIC_LINK - EMAIL_OTP - PUSH - DEVICE - SECURITY_KEY - PASSKEY - VERIFF - IPROOV - PALM_BIOMETRICS_RR - IDVERSE 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' NotFound: description: Not Found 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. ````