Server API
Endpoint: https://api.authsignal.com
The Authsignal Server API can be used to lookup users and track actions to initiate challenges.
SDKs
Authentication
The Authsignal Server API uses your secret key to authenticate requests. You should only ever call the Authsignal Server API from your server where your secret key can be stored securely. Your secret key should never be exposed to any public client.
You can find your secret key in the API Keys section of the Authsignal Portal settings page.
curl -u "YOUR_SECRET_KEY:" https://api.authsignal.com
Region selection
Authsignal's server SDKs defaults to the US (Oregon) region. If your tenant is in a different region, a different base URL must be configured.
Region | Base URL |
---|---|
US (Oregon) | https://api.authsignal.com/v1 |
AU (Sydney) | https://au.api.authsignal.com/v1 |
EU (Dublin) | https://eu.api.authsignal.com/v1 |
Retrieve user
GET /users/:userId
Use this endpoint to retrieve a user and their enrollment status. A user is considered to be enrolled if they have set up at least one authenticator which can be used to issue a challenge.
Request
userIdstring
The unique ID of the user in your database or IdP.
Response
isEnrolledboolean
True if the user is enrolled with at least one verification method and can be challenged.
allowedVerificationMethodsstring[]
The list of verification methods which the user is permitted to enroll.
enrolledVerificationMethodsstring[]
The list of verification methods which the user has enrolled.
defaultVerificationMethodenum
The user's default verification method.
emailstring
The user's email address.
phoneNumberstring
The user's phone number in E.164 format.
{
"isEnrolled": true,
"enrolledVerificationMethods": [
"EMAIL_MAGIC_LINK",
"PASSKEY"
],
"allowedVerificationMethods": [
"AUTHENTICATOR_APP",
"EMAIL_MAGIC_LINK",
"PASSKEY",
"PUSH",
"SMS"
],
"defaultVerificationMethod": "EMAIL_MAGIC_LINK",
"email": "user-123@gmail.com",
"phoneNumber": "+64271234567"
}
Track action
POST /users/:userId/actions/:action
Use this endpoint to record actions performed by users and initiate challenges.
Request
userIdstring
The unique ID of the user in your database or IdP.
actionstring
A short human-readable code which defines the action the user is performing, e.g. 'signIn'.
redirectUrlstring | undefined
The URL which the user will be redirected to after completing a challenge via the pre-built UI. Only required when using Authsignal's pre-built UI.
redirectToSettingsboolean | undefined
If set to true, the user will be redirected to 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 | undefined
The user's email address.
phoneNumberstring | undefined
The user's phone number in E.164 format.
ipAddressstring | undefined
The user's IP address. Should be provided when using rules based on location or other IP-derived features.
userAgentstring | undefined
The user agent identifying a browser or app. Should be provided when using rules based on device.
deviceIdstring | undefined
An ID which identifies the user's device. Should be provided when using rules based on device.
customobject | undefined
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.
cryptoobject | undefined
A JSON object containing crypto properties. Should be provided when using rules based on crypto data points.
{
"email": "test@example.com",
"deviceId": "XXX-XXX",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:100.0) Gecko/20100101 Firefox/100.0",
"ipAddress": "1.1.1.1",
"redirectUrl": "https://www.example.com/redirect-back",
"redirectToSettings": false,
"custom":{
"yourCustomBoolean": true,
"yourCustomString": "walletAddress",
"yourCustomNumber": 10.00
}
}
Response
stateenum
The current state of the action. The possible values are: CHALLENGE_REQUIRED, CHALLENGE_FAILED, CHALLENGE_SUCCEEDED, ALLOW, or BLOCK.
urlstring
The URL for intiating 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.
{
"state": "CHALLENGE_REQUIRED",
"idempotencyKey": "d44e68c9-d20c-4bdb-874a-fab5da5f997e",
"url": "https://mfa.authsignal.com/challenge?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
"isEnrolled": true
}
Get action status
GET /users/:userId/actions/:action/:idempotencyKey
Use this endpoint to determine the result of a challenge after the user has been redirected back from the Challenge UI (or after the popup has been closed, if showing the page in a modal).
Request
userIdstring
The unique ID of the user in your database or IdP.
actionstring
The code defining the action which was tracked.
idempotencyKeystring | undefined
The unique key which identifies the particular action which was tracked.
Response
stateenum
The current state of the action. The possible values are: CHALLENGE_REQUIRED, CHALLENGE_FAILED, CHALLENGE_SUCCEEDED, ALLOW, or BLOCK.
createdAttimestamp
The time in ISO 8061 format when the action was first created via track.
stateUpdatedAttimestamp
The time in ISO 8061 format when the state of the action was last updated.
{
"state": "CHALLENGE_REQUIRED",
"stateUpdatedAt": "2022-07-25T03:19:00.316Z",
"createdAt": "2022-07-25T03:19:00.317Z",
"ruleIds": []
}
Enroll verified authenticator
POST /users/:userId/authenticators
Use this endpoint to enroll an authenticator on behalf of a user if it has already been verified.
Request
userIdstring
The unique ID of the user in your database or IdP.
oobChannelenum
The channel of the out-of-band (OOB) authenticator. The possible values are: EMAIL_MAGIC_LINK or SMS.
emailstring | undefined
The user's verified email address.
phoneNumberstring | undefined
The user's verified phone number in E.164 format.
{
"oobChannel": "SMS",
"phoneNumber": "+130912341234"
}