Skip to main content

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.

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

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​

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.

POST /users/:userId/actions/:action

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

  • allowedVerificationMethodsstring[]

    The list of allowed verification methods for the action.

  • enrolledVerificationMethodsstring[]

    The subset of allowed verification methods for the action which the user has already enrolled.

  • defaultVerificationMethodenum

    The user's default verification method for the action.

POST /users/:userId/actions/:action

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

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.

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​

POST /users/:userId/authenticators

Use this endpoint to enroll an authenticator on behalf of a user if it has already been verified.

Request​

POST /users/:userId/authenticators

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