Authsignal’s server SDKs make it easier to interact with Authsignal’s REST API from your server-side code.

​
Repositories

Node.js

C#

Java

Ruby

Python

PHP

Go

​
Installation

npm install @authsignal/node

​
Initialization

Initialize the Authsignal client by providing your tenant’s secret key and the API URL for your region.

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

const authsignal = new Authsignal({
  apiSecretKey: "YOUR_SECRET_KEY",
  apiUrl: "YOUR_REGION_API_URL",
});

The API URLs for each region are defined below.

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

​
Usage

​
Track

API schema

This method lets you track authentication events performed by users and initiate challenges via the Authsignal pre-built UI or Client SDKs.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "signIn",
  attributes: {
    redirectUrl: "https://yourapp.com/callback",
  },
};

const response = await authsignal.track(request);

if (response.state === "CHALLENGE_REQUIRED") {
  // Present challenge via Authsignal pre-built UI URL
  const url = response.url;
} else if (response.state === "ALLOW") {
  // Allow the user to sign in
} else if (response.state === "BLOCK") {
  // Block the user from signing in
}

Learn more about how to track actions to implement MFA or passwordless login flows.

​
Validate Challenge

API schema

This method lets you validate server-side whether a user has successfully completed an authentication challenge via the Authsignal pre-built UI or an Authsignal Client SDK.

After obtaining a short-lived token from the pre-built UI or a Client SDK, pass this token to your server to determine the result.

const request = {
  token: "eyJhbGciOiJ...",
};

const response = await authsignal.validateChallenge(request);

if (response.state === "CHALLENGE_SUCCEEDED") {
  // The user completed the challenge successfully
  // Proceed with authenticated action or integrate with IdP to create authenticated session
} else {
  // The user did not complete the challenge successfully
}

​
Get User

API schema

This method lets you retrieve information about a user.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
};

const response = await authsignal.getUser(request);

const isEnrolled = response.isEnrolled;

​
Update User

API schema

This method lets you update information about a user. Any fields which are omitted in the request will be left unchanged.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  attributes: {
    email: "jane.smith@authsignal.com",
    phoneNumber: "+64271234567",
    username: "jane.smith@authsignal.com",
    displayName: "Jane Smith",
  },
};

const updatedAttributes = await authsignal.updateUser(request);

​
Delete User

API schema

This method lets you delete a user and all their associated authenticator data.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
};

await authsignal.deleteUser(request);

​
Get Authenticators

API schema

This method lets you retrieve a list of the authenticators that a user currently has enrolled.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
};

const authenticators = await authsignal.getAuthenticators(request);

​
Enroll Verified Authenticator

API schema

This method lets you enroll an email or SMS-based authenticator for a user whose email address or phone number has already been verified via an external platform.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  attributes: {
    verificationMethod: VerificationMethod.SMS,
    phoneNumber: "+64270000000",
  },
};

const response = authsignal.enrollVerifiedAuthenticator(request);

This method should not be used if you haven’t yet verified the user’s email or phone number. It does not send out an email / SMS to initiate a verification process - if you need to verify an email address or phone number, you should use a Client SDK or the pre-built UI.

​
Delete Authenticator

API schema

This method lets you remove an authenticator that a user has previously enrolled.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  userAuthenticatorId: "bf287470-24d9-4aa4-8b29-85683bea703f",
};

await authsignal.deleteAuthenticator(request);

​
Get Action

API schema

This method lets you retrieve information about an action which was previously tracked.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "signIn",
  idempotencyKey: "83d07321-9bba-4f08-a871-02e2af813b72",
};

const response = await authsignal.getAction(request);

​
Update Action

API schema

This method lets you manually update the state of an action that was previously tracked.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "signIn",
  idempotencyKey: "83d07321-9bba-4f08-a871-02e2af813b72",
  attributes: {
    state: "REVIEW_REQUIRED",
  },
};

const updatedAttributes = await authsignal.updateAction(request);

​
Initiate challenge

API schema

This method lets you initiate an SMS or email OTP challenge for a given phone number or email address.

const request = {
  verificationMethod: "SMS",
  phoneNumber: "+64271234567",
  action: "signInWithSms",
};

const response = await authsignal.challenge(request);

const challengeId = response.challengeId;

​
Verify challenge

API schema

This method lets you verify an SMS or email OTP challenge.

const request = {
  challengeId: "3a991a14-690c-492b-a5e5-02b9056a4b7d",
  verificationCode: "123456",
};

const response = await authsignal.verify(request);

const isVerified = response.isVerified;

​
Claim challenge

API schema

This method lets you claim a challenge on behalf of a user by associating it with an ID for the corresponding user record in your system.

const request = {
  challengeId: "3a991a14-690c-492b-a5e5-02b9056a4b7d",
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
};

const response = await authsignal.claimChallenge(request);

const token = response.token;

​
Get challenge

API schema

This method can be used to retrieve information about a currently active challenge.

const request = {
  challengeId: "3a991a14-690c-492b-a5e5-02b9056a4b7d",
};

const response = await authsignal.getChallenge(request);

​
Error handling

Authsignal Server SDKs can return errors for a variety of reasons, such as invalid requests or network interruptions, which should be handled accordingly.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
};

try {
  const response = await authsignal.getUser(request);
} catch (e) {
  if (e instanceof AuthsignalError) {
    const statusCode = e.statusCode;
    const errorCode = e.errorCode;
    const errorDescription = e.errorDescription;
  }
}

​
Error fields

​
statusCode
integer

The HTTP status code returned by the Authsignal Server API.

​
errorCode
string

A code which identifies a specific error state.

​
errorDescription
string

A free-text description of the error. This value should only be used for logging or troubleshooting purposes.

​
Error codes

​
invalid_configuration

Indicates that the request cannot be handled because the tenant is in an invalid configuration.

​
invalid_credential

Indicates that the credential (e.g. passkey) referenced by the request is invalid for the given user and cannot be authenticated.

​
invalid_request

Indicates that the request failed due to an invalid parameter or input.

​
too_many_requests

Indicates that the server cannot respond as requests have been rate-limited due to exceeding a threshold.

​
unauthorized

Indicates that the request is unauthorized due to invalid tenant credentials - for example if the API secret key is invalid or if the region doesn’t match.

​
Webhooks

​
Verifying incoming requests

The Authsignal Server SDK can be used to parse and verify incoming webhook events.

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

// Obtain raw request body and signature header
// For example using Express (https://expressjs.com/)
const payload = req.body;
const sig = req.headers["X-Signature-V2"];

const event = authsignal.webhook.constructEvent(payload, sig);

The Authsignal SDK requires the raw body of the request to verify the signature. If you’re using a framework, make sure it doesn’t manipulate the raw body as this will cause the signature verification to fail.

To prevent against replay attacks, the SDK will error if more than 5 minutes has elapsed since the time that the event was sent. This threshold can be customized by passing a tolerance value - the time (in minutes) after which requests should be rejected.

const payload = req.body;
const sig = req.headers["X-Signature-V2"];
const tolerance = 10;

const event = authsignal.webhook.constructEvent(payload, sig, tolerance);