Server API

Endpoint: https://signal.authsignal.com

The Authsignal Server API can be used to lookup users and track actions to initiate challenges.

Libraries

Node.js

Ruby

Python

PHP

C#

Go

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

curl -u "YOUR_SECRET_KEY:" https://signal.authsignal.com

Node.js

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

const authsignal = new Authsignal({ secret: "YOUR_SECRET_KEY" });

Ruby

Authsignal.setup do |config|
    config.api_secret_key = ENV["AUTHSIGNAL_SECRET_KEY"]
end

Python

import authsignal.client

authsignal_client = authsignal.Client(api_key='<SECRET API KEY HERE>')

PHP

Authsignal::setApiKey("<SECRET API KEY HERE>");

C#

using Authsignal;

var authsignal = new AuthsignalClient(secret: "YOUR_SECRET_KEY");

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://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.

Node.js

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

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

Ruby

Authsignal.setup do |config|
    config.api_secret_key = ENV["AUTHSIGNAL_SECRET_KEY"]
    config.base_uri = "https://au.signal.authsignal.com/v1"
end

Python

import authsignal.client

authsignal_client = authsignal.Client(api_key='<SECRET API KEY HERE>', api_url: 'https://au.signal.authsignal.com/v1')

PHP

Authsignal::setApiKey("<SECRET API KEY HERE>");
Authsignal::setApiHostname("https://au.signal.authsignal.com/v1")

C#

using Authsignal;

var authsignal = new AuthsignalClient(secret: "YOUR_SECRET_KEY", baseAddress: "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

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

Node.js

const result = await authsignal.getUser({ userId: "usr_123" });

if (result.isEnrolled) {
  // The user has set up MFA and can be challenged
} else {
  // The user has either not set up MFA or they have disabled it
}

Ruby

result = Authsignal.get_user(user_id: current_user.id)

is_enrolled = result[:is_enrolled]

Python

result = authsignal_client.get_user(user_id="usr_123")

is_enrolled = result["isEnrolled"]

PHP

$result = Authsignal::getUser(userId: "usr_123");

$isEnrolled = $result["isEnrolled"];

C#

var request = new UserRequest(UserId: "usr_123");

var response = await authsignal.GetUser(request);

if (response.IsEnrolled) {
  // The user has set up MFA and can be challenged
} else {
  // The user has either not set up MFA or they have disabled it
}

Request

• userIdstring

  The unique ID for this user in your database.

Response

• isEnrolledboolean

  Whether or not the user is enrolled with at least one authentication method and can be challenged.

• allowedVerificationMethodsstring[]

  An array of the allowed verification methods.

• enrolledVerificationMethodsstring[]

  An array of the user's enrolled authenticators.

• emailstring

  The user's email address.

• phoneNumberstring

  The user's phone number.

GET /users/:userId

{
  "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

The POST /users/:userId/actions/:action endpoint lets you record actions performed by users and initiate challenges.

Curl

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"}'

Node.js

const result = await authsignal.track({
  userId: "usr_123",
  action: "withdrawal",
  redirectUrl: "https://example.com/finalize-withdrawal",
});

if (result.state === "CHALLENGE_REQUIRED") {
  // The user should be presented with a challenge
}

Ruby

result = Authsignal.track_action({
        action_code: "signIn",
        idempotency_key: SecureRandom.uuid,
        redirect_url: redirect_url,
        user_id: "1234",
        email: "test@example.com",
        device_id: "XXX-XXX",
        user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:103.0) Gecko/20100101 Firefox/103.0",
        ip_address: "1.1.1.1",
        custom: {
            it_could_be_a_bool: true,
            it_could_be_a_string: "test",
            it_could_be_a_number: 400.00
        },
        crypto: {
          asset: "ETH",
          address: "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
          txnHash: "0x01994f9ee1b415a81f096ad20da8ecb3ae40b076eb486bb4191d62ae71b7ad0d",
          assetAmount: 0.01,
          assetAmountUsd: 17.96
        },
        redirectToSettings: false
    }
)

case result[:state]
when "ALLOW"
    # Carry on with your operation/business logic
when "BLOCK"
    # Stop your operations
when "CHALLENGE_REQUIRED"
    # Step up authentication required, redirect or pass the challengeUrl to the front end
    result[:challenge_url]
end

Python

import authsignal.client

result = authsignal_client.track_action(
    user_id="1234",
    action_code="testPython",
    payload={
        "redirectUrl": "https://www.example.com/",
        "email": "test@python.com",
        "deviceId": "XXX-XXX",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:103.0) Gecko/20100101 Firefox/103.0",
        "ipAddress": "1.1.1.1",
        "custom": {
            "yourOwnCustomBoolean": True,
            "yourOwnCustomString": "Blue",
            "yourOwnCustomDecimal": 100.00,
        },
        "crypto": {
          "asset": "ETH",
          "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
          "txnHash": "0x01994f9ee1b415a81f096ad20da8ecb3ae40b076eb486bb4191d62ae71b7ad0d",
          "assetAmount": 0.01,
          "assetAmountUsd": 17.96
        },
        "redirectToSettings": false
    }
)

match result["state"]
case authsignal.client.ALLOW:
    # Carry on with your operation/business logic
case authsignal.client.BLOCK:
    # Stop your operations
case authsignal.client.CHALLENGE_REQUIRED:
    # Step up authentication required, redirect or pass the challengeUrl to the front end
    response["challengeUrl"]

PHP

$idempotencyKey = "XXXX-XXXX";.
$redirectUrl = "https://www.yourapp.com/back_to_your_app";
$ipAddress = $_SERVER['HTTP_X_FORWARDED_FOR'] || $_SERVER['HTTP_X_REAL_IP'] ||  $_SERVER['REMOTE_ADDR'];

$payload = array(
            "redirectUrl" => $redirectUrl,
            "email" => "test@email",
            "deviceId" => $authsignalCookie,
            "userAgent" => $_SERVER["HTTP_USER_AGENT"],
            "ipAddress" => $ipAddress,
            "redirectToSettings" => false,
            "custom" => array(
              "yourCustomBoolean" => true,
              "yourCustomString" => true,
              "yourCustomNumber" => 1.12
            ),
            "crypto" => array(
              "asset" => "ETH",
              "address" => "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
              "txnHash" => "0x01994f9ee1b415a81f096ad20da8ecb3ae40b076eb486bb4191d62ae71b7ad0d",
              "assetAmount" => 0.01,
              "assetAmountUsd" => 17.96
            ));

$result = Authsignal::trackAction(userId: "123345",
                                  actionCode: "signIn",
                                  payload: $payload);

switch ($result["state"]) {
    case "ALLOW":
        // Carry on with your operation/business logic
        break;
    case "BLOCK":
        // Stop your operations
        break;
    case "CHALLENGE_REQUIRED":
        // Step up authentication required, redirect or pass the challengeUrl to the front end
        $response["challengeUrl"];
        break;
}

C#

var request = new TrackRequest(
  UserId: "usr_123",
  Action: "signIn",
  RedirectUrl: "https://example.com/callback");

var response = await authsignal.Track(request);

if (response.State === UserActionState.CHALLENGE_REQUIRED) {
  // The user should be presented with a challenge
}

Request

• userIdstring

  The unique ID for this user in your database.

• actionstring

  The code 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. Only required when using Authsignal's hosted challenge flows with redirects.

• 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 after a challenge. Use this if you want to allow users to manage their authenticators. Only relevant when using Authsignal's hosted challenge UI.

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 for intiating a challenge using Authsignal's hosted 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 used to call the Authsignal Client API directly to perform challenges. Use this if you're building your own UI rather than using Authsignal's hosted UI.

• isEnrolledboolean

  Whether or not the user is enrolled with at least one authentication method 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",
  "token": "123",
  "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

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

Node.js

const result = await authsignal.getAction({
  userId: "usr_123",
  action: "signIn",
  idempotencyKey: "ik_123",
});

if (result.state === "CHALLENGE_SUCCEEDED") {
  // The user successfully completed the challenge
  // Proceed with the withdrawal
}

Ruby

result = Authsignal.get_action(
    user_id: "1234",
    action_code: "signIn",
    idempotency_key: "15cac140-f639-48c5-92db-835ec8d3d144")
if (result.state === "CHALLENGE_SUCCEEDED") {
    // The user successfully completed the challenge
    // Proceed with the signIn
}

Python

result = authsignal_client.get_action(
    user_id="1234",
    action_code="signIn",
    idempotency_key="0ae73782-d8c1-49bc-be75-09612a3b9d1c",
)

if result["state"] == "CHALLENGE_SUCCEEDED":
    print("Procceed with business logic")
    # The user has successfully completed the challenge, and you should proceed with
    # the business logic

PHP

$result = Authsignal::getAction(userId: "123",
                                actionCode: "signIn",
                                idempotencyKey: "2320ce18-91be-47a8-9bbf-eec642807c34");

if($result["state"] === "CHALLENGE_SUCCEEDED"){
  // The user has successfully completed the challenge,
  // and you should proceed with the business logic
}

C#

var request = new ActionRequest(
  UserId: "usr_123",
  Action: "signIn",
  IdempotencyKey: "ik_123");

var response = await authsignal.GetAction(request);

if (response.State === UserActionState.CHALLENGE_SUCCEEDED) {
  // The user successfully completed the challenge
}

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

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

Node.js

await authsignal.enrollVerifiedAuthenticator({
  userId: "usr_123",
  oobChannel: "SMS",
  phoneNumber: "+64271234567",
});

Ruby

Authsignal.enrol_authenticator(user_id: "1234",
                              authenticator:{ oob_channel: "SMS",
                                              phone_number: "+64270000000" })

Python

authsignal_client.enrol_authenticator(
    user_id="1234",
    authenticator_payload={"oobChannel": "SMS", "phoneNumber": " 64277770770"},
)

PHP

Authsignal::enrolAuthenticator(userId: "1234",
                              authenticator: array("oobChannel" => "SMS",
                                                  "phoneNumber" => "+64270000000"));

C#

var request = AuthenticatorRequest(
  UserId: userId,
  OobChannel: OobChannel.SMS,
  PhoneNumber: "+64270000000");

var response = await authsignal.EnrollVerifiedAuthenticator(request);

Request

• userIdstring

  The unique ID for this user in your database.

• oobChannelenum

  The channel of the out-of-band (OOB) authenticator. Possible values are EMAIL_MAGIC_LINK or SMS.

• phoneNumberstring | undefined

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

• emailstring | undefined

  The user's verified email address.

POST /users/:userId/authenticators

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