Skip to content

Mobile Biometrics

Login users with native mobile biometrics. This process relies on the device ability to leverage built-in biometric sensors. To support mobile biometrics in the app, first implement the SDK call that creates an authenticator (cryptographic key-pair) on the end-user device and then register this authenticator with Transmit. The private key remains securely stored on the device and protected by biometrics, while the public key is registered with Transmit for a given user. To authenticate, the device uses mobile biometrics to access the private key and to sign a challenge that gets verified by Transmit. Note: registration and authentication are two-step procedures that start by calling the client-side SDK provided by Transmit, and complete using these APIs.

Download OpenAPI description
backend-mobile-biometrics.openapi.json
backend-mobile-biometrics.openapi.yaml
Languages
Servers
Sandbox environment
https://api.sbx.transmitsecurity.io/cis/
Production environment (US)
https://api.transmitsecurity.io/cis/
Production environment (EU)
https://api.eu.transmitsecurity.io/cis/
Production environment (CA)
https://api.ca.transmitsecurity.io/cis/
Production environment (AU)
https://api.au.transmitsecurity.io/cis/

Create mobile biometrics challenge

Request

Creates a challenge for the user to sign for the mobile biometrics flow.

Security
ClientAccessToken
Bodyapplication/jsonrequired
resourcestring

Resource URI the authentication request is attempting to access, which is reflected in the audience (aud claim) of the access token. This must be configured as resource for the application.

claimsobject
Example: {"id_token":{"roles":null}}
org_idstring

Organization ID, used for member login in B2B scenarios

client_attributesobject
session_idstring

Used to associate the authentication with an existing session (such as for MFA). If unspecified, a new session is created and the session ID is returned.

user_idstringrequired

ID of the user

approval_dataobject

Flat object that contains the data that your customer should approve for a transaction signing or custom approval flow. It can contain up to 10 keys, and only alphanumeric characters, underscores, hyphens, and periods. It will be returned as a claim in the ID token upon successful authentication.

Example: {"transaction_id":"eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT","sum":"200"}
timeoutnumber
Default 600
curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/mobile-biometrics/start \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource": "string",
    "claims": {
      "id_token": {
        "roles": null
      }
    },
    "org_id": "string",
    "client_attributes": {
      "user_agent": "string",
      "ip_address": "string"
    },
    "session_id": "string",
    "user_id": "string",
    "approval_data": {
      "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
      "sum": "200"
    },
    "timeout": 600
  }'

Responses

Backend auth initialized successfully.

Bodyapplication/json
challengestringrequired
Response
application/json
{
  "challenge": "string"
}

Authenticate with mobile biometrics

Request

Completes authentication in Transmit. Before calling this API, invoke the client-side SDK provided by Transmit to sign a challenge using the private key stored by the device, which only occurs after the user verifies themselves with biometrics. Returns an access token for the user associated with the key.

Security
ClientAccessToken
Bodyapplication/jsonrequired
resourcestring

Resource URI the authentication request is attempting to access, which is reflected in the audience (aud claim) of the access token. This must be configured as resource for the application.

claimsobject
Example: {"id_token":{"roles":null}}
org_idstring

Organization ID, used for member login in B2B scenarios

client_attributesobject
session_idstring

Used to associate the authentication with an existing session (such as for MFA). If unspecified, a new session is created and the session ID is returned.

signaturestringrequired

Signed challenge returned by SDK authentication call

challengestringrequired

A string used to create attestation

key_idstringrequired

ID of the key

user_idstringrequired

ID of the user

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/mobile-biometrics/authenticate \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource": "string",
    "claims": {
      "id_token": {
        "roles": null
      }
    },
    "org_id": "string",
    "client_attributes": {
      "user_agent": "string",
      "ip_address": "string"
    },
    "session_id": "string",
    "signature": "string",
    "challenge": "string",
    "key_id": "string",
    "user_id": "string"
  }'

Responses

Returns user tokens

Bodyapplication/json
access_tokenstringrequired

User access token for accessing endpoints on behalf of the authenticated user.

id_tokenstring

ID token that identifies the user.

refresh_tokenstring

Refresh token used to refresh an expired access token.

token_typestringrequired

Bearer.

expires_innumberrequired

Expiration time of the access token in seconds.

Default 3600
session_idstringrequired

ID of the session in which the authentication occurs.

Response
application/json
{
  "access_token": "string",
  "id_token": "string",
  "refresh_token": "string",
  "token_type": "string",
  "expires_in": 3600,
  "session_id": "string"
}

Register mobile biometrics

Request

Completes mobile biometrics registration in Transmit. Before calling this API, create an authenticator (cryptographic key-pair) on the end-user's device by invoking the client-side SDK provided by Transmit. This API must be called from the backend using the user access token returned upon successful authentication. If successful, the mobile biometrics authenticator will be registered for the user that corresponds to the authorization token.

Security
UserAccessToken
Bodyapplication/jsonrequired
publicKeystringrequired

Public key generated by SDK registration call

publicKeyIdstringrequired

ID of the public key

encryptionTypestring

Encryption type

Default "rsa"
Enum"rsa""ec"
challengestring

A string used to create attestation

attestation_encoded_resultstring

Encoded attestation data

osstringrequired

OS type

displayNamestring

Display name for the crypto key

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/mobile-biometrics/register \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "publicKey": "string",
    "publicKeyId": "string",
    "encryptionType": "rsa",
    "challenge": "string",
    "attestation_encoded_result": "string",
    "os": "string",
    "displayName": "string"
  }'

Responses

Register mobile biometrics

Response
No content

Delete mobile biometrics

Request

Deletes mobile biometrics authenticator for a user that is currently logged in. This API must be called from the backend using the user access token. If successful, the key will be deleted for the user that corresponds to the authorization token.

Security
UserAccessToken
Bodyapplication/jsonrequired
publicKeyIdstringrequired

ID of the public key

curl -i -X DELETE \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/mobile-biometrics/delete \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "publicKeyId": "string"
  }'

Responses

Key deleted

Response
No content