In-app verification

Check out our end-to-end guide on how to implement in-app verification.

Credential storage modes

In-app credentials can be stored either as a single credential for the device or as separate credentials per username. If you do not pass a username when adding, getting, removing, or verifying with an in-app credential, the SDK uses one credential for the device. This is useful for step-up verification when the current signed-in user is the only user expected to use the device credential. If a different user later adds an in-app credential on the same device without a username, the credential is rebound to that user. If you pass a username, the SDK stores and looks up a credential scoped to that username. This lets multiple users sign in on the same device without removing each other’s in-app credentials. Use the same username when calling addCredential, getCredential, removeCredential, and verify. PIN methods always require a username, because each PIN is associated with a username on the device.

Adding a credential

Adding an in-app credential generates a private/public key pair, where the private key is secured on the user’s mobile device and the public key is held by Authsignal. This operation must be authorized with a short-lived token, which can be obtained by tracking an action from your backend in an authenticated context.

await authsignal.inapp.addCredential(
    token: "eyJhbGciOiJ...",
    username: "jane.smith@authsignal.com"
)

authsignal.inapp.addCredential(
    token = "eyJhbGciOiJ...",
    username = "jane.smith@authsignal.com"
)

await authsignal.inapp.addCredential({
  token: "eyJhbGciOiJ...",
  username: "jane.smith@authsignal.com",
});

await authsignal.inapp.addCredential(
  token: "eyJhbGciOiJ...",
  username: "jane.smith@authsignal.com",
);

Parameters

string

A short-lived token obtained by tracking an action.

string

An optional username used to store a separate in-app credential for this user on the device. Omit this value to use a single device credential.

boolean

When set to true, the SDK will generate a platform-specific attestation during enrollment:

iOS: Uses App Attest (DCAppAttestService) to generate an attestation bound to the device.
Android: Uses Play Integrity to generate an integrity token.

The attestation is generated internally by the SDK and sent to the Authsignal server for verification. This provides an additional layer of assurance that the credential is being enrolled from a legitimate app on a real device.

Response

AuthsignalResponse<AppCredential>

Show properties

string

An unstructured error description present if the SDK call encountered an error.

string

A formatted error code which may additionally be present if the SDK call encountered an error. Possible values are: token_not_set, expired_token or network_error.

AppCredential | null

Show properties

string

required

The ID of the app credential.

string

required

The date and time the app credential was created.

string

required

The user ID of the user that the app credential belongs to.

Getting a credential

Get information about the in-app credential stored on the device, if one exists.

let response = await authsignal.inapp.getCredential(username: "jane.smith@authsignal.com")

val response = authsignal.inapp.getCredential(username = "jane.smith@authsignal.com")

const response = await authsignal.inapp.getCredential({
  username: "jane.smith@authsignal.com",
});

final response = await authsignal.inapp.getCredential(
  username: "jane.smith@authsignal.com",
);

Parameters

string

An optional username used to look up a credential scoped to that username. Omit this value to look up the single device credential.

Response

AuthsignalResponse<AppCredential>

Show properties

string

An unstructured error description present if the SDK call encountered an error.

string

A formatted error code which may additionally be present if the SDK call encountered an error. Possible values are: invalid_credential when the credential exists on the device but has been removed from the server.

AppCredential

Show properties

string

required

The ID of the app credential.

string

required

The date and time the app credential was created.

string

The date and time the app credential was last used for authentication. Will be null if the credential has never been used.

string

required

The user ID of the user that the app credential belongs to.

Removing a credential

await authsignal.inapp.removeCredential(username: "jane.smith@authsignal.com")

authsignal.inapp.removeCredential(username = "jane.smith@authsignal.com")

await authsignal.inapp.removeCredential({
  username: "jane.smith@authsignal.com",
});

await authsignal.inapp.removeCredential(username: "jane.smith@authsignal.com");

Parameters

string

An optional username used to remove the credential scoped to that username. Omit this value to remove the single device credential.

Response

AuthsignalResponse<boolean>

Show properties

string

An unstructured error description present if the SDK call encountered an error. This could occur if the credential on the device is no longer valid because the corresponding user authenticator has been deleted in the Authsignal Portal.

boolean

True if the app credential was successfully removed.

Verifying an action

Verify an action in your app using the credential stored securely on the device.

let response = await authsignal.inapp.verify(username: "jane.smith@authsignal.com")

let token = response.data?.token

val response = authsignal.inapp.verify(username = "jane.smith@authsignal.com")

val token = response.data?.token

const response = await authsignal.inapp.verify({
  username: "jane.smith@authsignal.com",
});

const token = response.data?.token;

final response = await authsignal.inapp.verify(
  username: "jane.smith@authsignal.com",
);

final token = response.data?.token;

Parameters

string

An optional action code to use for the verification.

string

An optional username used to verify with the credential scoped to that username. Omit this value to verify with the single device credential.

Response

AuthsignalResponse<VerifyDeviceResponse>

Show properties

string

VerifyDeviceResponse

Show properties

string

required

A token which can be used for server-side validation.

string

required

The user ID of the user that the device credential belongs to.

string

required

The user authenticator ID that the device credential belongs to.

string

The username of the user that the device credential belongs to.

Creating a PIN

Create a custom PIN backed by a cryptographic in-app credential stored securely on the user’s device.

let response = await authsignal.inapp.createPin(
    token: "eyJhbGciOiJ...",
    username: "jane.smith@authsignal.com",
    pin: "123456"
)

val response = authsignal.inapp.createPin(
    token = "eyJhbGciOiJ...",
    username = "jane.smith@authsignal.com",
    pin = "123456",
)

const response = await authsignal.inapp.createPin({
  token: "eyJhbGciOiJ...",
  username: "jane.smith@authsignal.com",
  pin: "123456",
});

final response = await authsignal.inapp.createPin(
  token: "eyJhbGciOiJ...",
  username: "jane.smith@authsignal.com",
  pin: "123456",
);

Parameters

string

A short-lived token obtained by tracking an action.

string

The username associated with the PIN. A device can have multiple PINs stored for different users.

string

The PIN value. Must be a valid 6-digit numeric value.

Response

AuthsignalResponse<AppCredential>

Show properties

string

An unstructured error description present if the SDK call encountered an error.

string

A formatted error code which may additionally be present if the SDK call encountered an error. Possible values are: token_not_set, expired_token or network_error.

AppCredential | null

Show properties

string

required

The ID of the app credential.

string

required

The date and time the app credential was created.

string

required

The user ID of the user that the app credential belongs to.

Verifying a PIN

Check a submitted PIN value against the value stored on the device and use the associated in-app credential to verify the user.

let response = await authsignal.inapp.verifyPin(
    username: "jane.smith@authsignal.com",
    pin: "123456"
)

let isVerified = response.data?.isVerified
let token = response.data?.token

val response = authsignal.inapp.verifyPin(
    username = "jane.smith@authsignal.com",
    pin = "123456",
)

val isVerified = response.data?.isVerified
val token = response.data?.token

const response = await authsignal.inapp.verifyPin({
  username: "jane.smith@authsignal.com",
  pin: "123456",
});

const isVerified = response.data?.isVerified;
const token = response.data?.token;

final response = await authsignal.inapp.verifyPin(
  username: "jane.smith@authsignal.com",
  pin: "123456",
);

final isVerified = response.data?.isVerified;
final token = response.data?.token;

Response

AuthsignalResponse<VerifyPinResponse>

Show properties

string

VerifyPinResponse

Show properties

boolean

required

True if PIN verification is successful.

string

required

A token which can be used for server-side validation.

string

required

The user ID of the user that the PIN and in-app credential belong to.

Get PIN usernames on device

Get all the usernames for PINs currently stored on the device. This method can be used if allowing multiple users to create PINs on the same device.

let response = await authsignal.inapp.getAllPinUsernames()

let usernames = response.data

val response = authsignal.inapp.getAllPinUsernames()

val usernames = response.data

const response = await authsignal.inapp.getAllPinUsernames();

const usernames = response.data;

final response = await authsignal.inapp.getAllPinUsernames();

final usernames = response.data;

Response

AuthsignalResponse<string[]>

Show properties

string

An unstructured error description present if the SDK call encountered an error.

string[]

An array of usernames for all the PINs currently stored on the device

Server

Client

Call Connect

Credential storage modes

Adding a credential

Parameters

Response

Getting a credential

Parameters

Response

Removing a credential

Parameters

Response

Verifying an action

Parameters

Response

Creating a PIN

Parameters

Response

Verifying a PIN

Response

Get PIN usernames on device

Response

​Credential storage modes

​Adding a credential

​Parameters

​Response

​Getting a credential

​Parameters

​Response

​Removing a credential

​Parameters

​Response

​Verifying an action

​Parameters

​Response

​Creating a PIN

​Parameters

​Response

​Verifying a PIN

​Response

​Get PIN usernames on device

​Response

Credential storage modes

Adding a credential

Parameters

Response

Getting a credential

Parameters

Response

Removing a credential

Parameters

Response

Verifying an action

Parameters

Response

Creating a PIN

Parameters

Response

Verifying a PIN

Response

Get PIN usernames on device

Response