Sign in

v1

latestOpenAPI 3.1.02026-07-268342124.0 KB
users

Track action

Record authentication events performed by users and initiate challenges via Authsignal's pre-built UI or Authsignal Client SDKs.

post/users/{userId}/actions/{action}

Path parameters

userIdstring required

The ID of the user.

actionstring required

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)}$.

Request body

redirectUrlstring

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.

redirectToSettingsboolean

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.

emailstring

The user's email address.

phoneNumberstring

The user's phone number in E.164 format.

ipAddressstring

The user's IP address. Should be provided when using rules based on location or other IP-derived features.

userAgentstring

The user agent identifying a browser or app. Should be provided when using rules based on device.

deviceIdstring

An ID which identifies the user's device. Should be provided when using rules based on device.

scopestring

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.

customobject

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.

localestring

The locale of the user in BCP 47 format. Used to localize the pre-built UI, email, and SMS messages.

customDomainstring

The custom domain to use for the pre-built UI. If not provided, the default domain will be used.

Example request

{
  "locale": "es"
}

Response

OK

state'ALLOW' | 'BLOCK' | 'CHALLENGE_REQUIRED' | 'CHALLENGE_FAILED' | 'CHALLENGE_SUCCEEDED' | 'REVIEW_REQUIRED' | 'REVIEW_FAILED' | 'REVIEW_SUCCEEDED'

The current state of the action.

urlstring

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.

tokenstring

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.

isEnrolledboolean

True if the user is enrolled with at least one verification method and can be challenged.

idempotencyKeystring

A unique key which identifies a particular action. This key can be used to determine if the user has successfully completed a challenge.

allowedVerificationMethodsVerificationMethod[]

The list of verification methods which the user is permitted to enroll.

enrolledVerificationMethodsVerificationMethod[]

The list of verification methods which the user has enrolled.

defaultVerificationMethod'SMS' | 'AUTHENTICATOR_APP' | 'EMAIL_MAGIC_LINK' | 'EMAIL_OTP' | 'PUSH' | 'DEVICE' | 'SECURITY_KEY' | 'PASSKEY' | 'VERIFF' | 'IPROOV' | 'PALM_BIOMETRICS_RR' | 'IDVERSE'
ruleIdsstring[]

The IDs of the triggered rules.