Skip to main content

Server API

Endpoint: https://signal.authsignal.com

The Authsignal Server API can be used to identify users, to query their MFA setup, and to track actions against them which could require an MFA challenge.

Libraries

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 Dashboard settings.

curl -u "YOUR_SECRET_KEY:" https://signal.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.

RegionBase URL
US (Oregon)https://signal.authsignal.com/v1
AU (Sydney)https://au.signal.authsignal.com/v1
EU (Dublin)https://eu.signal.authsignal.com/v1

Here are examples of different SDKs setting the base URL to use our AU endpoint.

import { Authsignal } from "@authsignal/node";

const authsignal = new Authsignal({ secret: "YOUR_SECRET_KEY", apiBaseUrl: "https://au.signal.authsignal.com/v1" });

Retrieve user

The GET /users/:userId endpoint retrieves a user and their MFA 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.

curl https://signal.authsignal.com/v1/users/usr_123 \
-u YOUR_SECRET_KEY:

Request

Response

GET /users/:userId

{
"isEnrolled": true,
"enrolledVerificationMethods": [
"SMS",
"AUTHENTICATOR_APP",
"RECOVERY_CODE",
"EMAIL_MAGIC_LINK",
"PUSH",
"SECURITY_KEY",
"PASSKEY"
],
"allowedVerificationMethods": [
"AUTHENTICATOR_APP",
"PUSH",
"PASSKEY",
"SMS",
"EMAIL_MAGIC_LINK"
],
"defaultVerificationMethod": "AUTHENTICATOR_APP",
"email": "user-123@gmail.com"
}

Track user action

The POST /users/:userId/actions/:action endpoint lets you record the actions which your users perform and it will determine if these actions need to be gated behind an MFA challenge.

curl https://signal.authsignal.com/v1/users/usr_123/actions/withdrawal \
-u YOUR_SECRET_KEY: \
-H "Content-Type: application/json" \
-d '{"redirectUrl": "https://example.com/finalize-withdrawal"}'

Request

  • userIdstring

    The unique ID for this user in your database.

  • actionstring

    The name of the action as defined in the Authsignal Portal.

  • idempotencyKeystring | undefined

    A unique key which identifies the instance of the action that the user is performing. This can be an ID in your own app domain, such as a transaction ID or shopping cart ID, or if not provided one is generated automatically. Use this to lookup the status of the action after a challenge.

  • redirectUrlstring | undefined

    The URL for the user to get redirected back to when exiting from the Challenge UI. Required when the page is presented via a redirect but not when presented as a popup.

  • ipAddressstring | undefined

    The IP address of the user performing the action

  • emailstring | undefined

    The email address of the user performing the action

  • userAgentstring | undefined

    The user agent of the user performing the action

  • deviceIdstring | undefined

    The ID of user's device. This could be a mobile device ID or the anonymousId returned by the Authsignal Browser web client.

  • customobject | undefined

    A custom JSON object. Use this attribute to send a list of custom data points. Rules can be used to match against these data points.

  • cryptoobject | undefined

    A crypto object. Use this attribute to send crypto related metadata and Know Your Transaction (KYT) use cases.

  • redirectToSettingsboolean | undefined

    The flag to indicate if you want to redirect the user to their settings page, use this if you want to allow your user to manage their authenticators, defaults to false

POST /users/:userId/actions/:action

{
"idempotencyKey":"d44e68c9-d20c-4bdb-874a-fab5da5f997e",
"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",
"custom":{
"yourCustomBoolean": true,
"yourCustomString": "walletAddress",
"yourCustomNumber": 10.00
},
"crypto": {
"asset": "ETH",
"address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
"txnHash": "0x01994f9ee1b415a81f096ad20da8ecb3ae40b076eb486bb4191d62ae71b7ad0d",
"assetAmount": 0.01,
"assetAmountUsd": 17.96
},
"redirectToSettings": false
}

Response

  • stateenum

    The current state of the action. The possible values are: CHALLENGE_REQUIRED, CHALLENGE_FAILED, CHALLENGE_SUCCEEDED, ALLOW, or BLOCK.

  • urlstring

    The URL of the Challenge UI. You can redirect to this URL to challenge the user if the state determines that a challenge is required, or if you want to allow the user to enroll for MFA or to manage their existing MFA settings.

  • isEnrolledboolean

    Whether or not the user is enrolled for MFA and can be challenged.

  • idempotencyKeystring

    A unique key which identifies the instance of the action that the user is performing.

POST /users/:userId/actions/:action

{
"state": "CHALLENGE_REQUIRED",
"idempotencyKey": "d44e68c9-d20c-4bdb-874a-fab5da5f997e",
"url": "https://mfa.authsignal.com/challenge",
"isEnrolled": true
}

Get action status

The GET /users/:userId/actions/:action/:idempotencyKey endpoint lets you 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).

curl https://signal.authsignal.com/v1/users/usr_123/actions/withdrawal/ik_123 \
-u YOUR_SECRET_KEY:

Request

  • userIdstring

    The unique ID for this user in your database.

  • actionstring

    The name of the action as defined in the Authsignal Portal.

  • idempotencyKeystring | undefined

    A unique key which identifies the instance of the action that the user is performing. This can be an ID in your own app domain, such as a transaction ID or shopping cart ID, or if not provided one is generated automatically.

Response

  • stateenum

    The current state of the action. The possible values are: CHALLENGE_REQUIRED, CHALLENGE_FAILED, CHALLENGE_SUCCEEDED, ALLOW, or BLOCK.

  • stateUpdatedAttimestamp

    The time in ISO 8061 format when the state of the action was last updated.

  • createdAttimestamp

    The time in ISO 8061 format when the action was first created via track.

GET /users/:userId/actions/:action/:idempotencyKey

{
"state": "CHALLENGE_REQUIRED",
"stateUpdatedAt": "2022-07-25T03:19:00.316Z",
"createdAt": "2022-07-25T03:19:00.317Z",
"ruleIds": []
}

Enroll verified authenticator

The POST /users/:userId/authenticators endpoint can be used to enroll an authenticator on behalf of a user if it has already been verified.

curl https://signal.authsignal.com/v1/users/usr_123/authenticators \
-u YOUR_SECRET_KEY: \
-H "Content-Type: application/json" \
-d '{"oobChannel": "SMS", "phoneNumber": "+64271234567"}'

Request

POST /users/:userId/authenticators

{
"oobChannel": "SMS",
"phoneNumber": "+130912341234"
}