​
Users

​
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);

​
Authenticators

​
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);

​
Actions

​
Track Action

API schema

This method lets you track authentication actions 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.

​
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);

​
Challenges

​
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 by determining if the OTP code submitted by the user is valid.

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);

​
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
}

​
Sessions

​
Create Session

API schema

This method can be used to convert a challenge into an authenticated session. If the challenge associated with the client token was successful, it will return an access token and refresh token.

const request = {
  token: "eyJhbGciOiJ...",
  clientId: "46e10ac5-cb9c-458f-ad86-0f698f67b365",
};

const response = await authsignal.createSession(request);

const accessToken = response.accessToken;
const refreshToken = response.refreshToken;

​
Validate Session

API schema

This method can be used to validate a session for a given access token. This will ensure both that the token signature is valid and that the token has not been revoked.

const request = {
  accessToken: "eyJhbGciOiJ...",
  clientIds: ["46e10ac5-cb9c-458f-ad86-0f698f67b365"],
};

const response = await authsignal.validateSession(request);

const userId = response.user.userId;
const email = response.user.email;

​
Refresh Session

API schema

This method can be used to refresh a session for a given refresh token. This will return a new access token and refresh token, revoking any previously issued tokens.

const request = {
  refreshToken: "3f72a26e6834b4da...",
};

const response = await authsignal.refreshSession(request);

const accessToken = response.accessToken;
const refreshToken = response.refreshToken;

​
Revoke Session

API schema

This method can be used to revoke a session for a given access token.

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

await authsignal.revokeSession(request);

​
Revoke User Sessions

API schema

This method can be used to revoke all active sessions for a given user.

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

await authsignal.revokeUserSessions(request);