Creating and logging in users

This article explains how production accounts can create users (and log in existing users) with the Apto Mobile API. If you are looking to create a cardholder with the Core API, see Issuing cards with the Core API, but note that for compliance reasons only approved Enterprise customers can create cardholders with the Core API. Most card programs – including all Instant Issuance programs – use the Mobile API.

Apto makes a distinction between a “user” and a “cardholder”: a user remains a user until you issue them a card. From this point forward they are a cardholder. All cardholders are users, but not all users are cardholders.

At the end of this process, you will have a user session token that can be used to authorize card issuance. Subsequently, the user session token can be used to authorize other actions like listing card transactions.

note

If you’re looking for instructions for creating test users in our sandbox, see Creating test cardholders.

Creating a new user with the Mobile API#

There are three steps required to create a user with the Mobile API:

  1. Request the API to send a verification code to the new user via SMS
  2. Complete user verification by sending a code (One Time Passcode) back to the API
  3. Create the verified user

Developers can manage these steps in one of three ways, listed here in order of lowest to highest level of abstraction:

  1. Directly through the Mobile API (maintains flexibility at the expense of complexity)
  2. Through Apto’s Mobile SDKs (seamless API integration while retaining UI control)
  3. Through our Demo application (an “out-of-the-box” option for speed to market)

This article (and the proceeding article on issuing cards) discusses direct integration with the Mobile API. However, under the hood, the following steps are the same for all three approaches and therefore should be useful for any developer looking to understand the process. Learn more about SDK integration here and the Demo application here.

User verification overview#

Let’s start by looking at how user verification works in a general sense.

The Apto Mobile API uses user session tokens to authenticate protected cardholder API interactions and maintain proper compliance.

Before a user is created or logged in, Apto will need to verify their identity (and obtain their consent) through a process of credential verification. There are two types of credentials: primary and secondary. A user’s primary credential can be their email address or phone number depending on program configuration. In the case of Instant Issuance, it is always the phone number. A user’s secondary credential can be a date of birth or either of the unused primary credential options. In the case of Instant Issuance, it is always their date of birth.

When creating new users, only the primary credential is needed. However, before a user can become a cardholder (via the Issuing cards process), they will need to provide secondary credential data, which will be used alongside the primary credential to obtain a user session token. This flow is discussed below in Logging in a user with the Mobile API.

Step 1: Send a verification code to the new user#

Begin the verification process by sending a POST request to the /verifications/start endpoint with the user's phone number:

{
"datapoint": {
"data_type": "phone",
"country_code": "1",
"phone_number": "2105555555"
},
"datapoint_type": "phone"
}

When you submit this request, we send a six digit one-time password (OTP) via SMS to the user's phone number. The OTP expires after 15 minutes. The response includes a verification object, identified by the verification_id field with a status of “pending”:

{
"type": "verification",
"verification_id": "entity_27288bc122db1339",
"status": "pending"
}

Save this verification ID, it will be needed in step two.

Step 2: Complete the new user verification#

Once the user receives the OTP, they should enter it into your app. You can then send a POST request with this OTP to the /verifications/{verification_id}/finish endpoint (where verification_id is the phone verification ID you saved in step one) to complete the verification. Note that the OTP received by the user will include a dash (eg: “111-222”), but just the numbers should be returned to the API:

{
"secret": "111222"
}

The response will include the status of the verification, which can be "pending", "passed", "failed", or "expired" (in most cases, for US phone numbers, it should at this point be “passed”):

{
"type": "verification",
"verification_id": "entity_27288bc122db1339",
"status": "passed"
}

Step 3: Create the user in your program#

Once the user's verification status is “passed”, you can use their primary credential verification_id to create a user. This is also the best opportunity to collect additional required user data – their secondary credential (DOB), email, home address, Social Security number – that will be required to issue a card or login.

To create a user from a verified primary credential, send a POST request to the /user endpoint. Note that the data array includes the primary verification (with its verification_id) and all of the additional information required for issuing a card:

{
"data_points": {
"type": "list",
"data": [
{
"type": "phone",
"country_code": "1",
"phone_number": "20155555555",
"verification_id": "entity_9749a9aea2bccb7a"
},
{
"type": "email",
"email": "tony.stark@aptopayments.com"
},
{
"type": "birthdate",
"birthdate": "1965-10-20"
},
{
"type": "name",
"first_name": "Tony",
"last_name": "Stark"
},
{
"value": "111223333",
"country": "US",
"doc_type": "SSN",
"data_type": "id_document"
},
{
"type": "address",
"street_one": "Malibu Point 10880",
"street_two": "",
"locality": "Malibu",
"region": "CA",
"postal_code": "90265",
"country": "US"
}
]
}
}

This request ensures the primary credential verification is valid, and then creates the user. The response contains the user_id and user_token (user session token) for the new user:

{
"type": "user",
"user_id": "crdhldr_b04f29605a018f7d72a2",
"user_token": "{USER_SESSION_TOKEN}",
"user_data": {
"type": "list",
"data": [
{
"type": "phone",
"country_code": "1",
"phone_number": "2015555555"
}
],
"page": 0,
"rows": 5,
"has_more": true,
"total_rows": 10
}
}

You're now ready to issue a card to this user, at which point they are classified a cardholder.

Logging in a user with the Mobile API#

There are four steps required to login an existing user with the Mobile API:

  1. Send a verification code to the user’s primary credential
  2. Verify the user’s primary credential
  3. Verify the user’s secondary credential
  4. Log in the user

Step 1: Send a verification code to the user#

You can begin the verification process by sending a POST request to the /verifications/start endpoint with the user's phone number (or email if email is the primary credential):

{
"datapoint": {
"data_type": "phone",
"country_code": "1",
"phone_number": "2105555555"
},
"datapoint_type": "phone"
}

When you submit this request, we send a six digit one-time password (OTP) via SMS to the user's phone number. The OTP expires after 15 minutes. The response includes a verification object, identified by the verification_id field with a status of “pending”:

{
"type": "verification",
"verification_id": "entity_27288bc122db1339",
"status": "pending"
}

Hang on to this verification ID, it will be needed in step two.

Step 2: Verify the user’s primary credential#

Once the user receives the OTP, they should enter it into your app. You can then send a POST request with this OTP to the /verifications/{verification_id}/finish endpoint (where verification_id is the phone verification ID you saved in step one) to complete the verification. Note that the OTP received by the user will include a dash (eg: “111-222”), but just the numbers should be returned to the API:

{
"secret": "111222"
}

The response will include the status of the verification, which should be "passed", along with a secondary_credential property, identified by the secondary credential verification_id and the required verification_type:

{
"type": "verification",
"verification_id": "entity_27288bc122db1339",
"status": "passed",
"secondary_credential": {
"verification_id": "entity_baae28af702d231f",
"type": "verification",
"verification_type": "birthdate",
"status": "pending"
}
}

Step 3: Verify the user’s secondary credential#

This process is almost identical to step two. Send a POST request to the /verifications/{verification_id}/finish endpoint. However, this time use the secondary_credential verification_id obtained in step two and – assuming the secondary credential is the date of birth – set the value of secret to the user’s birthday in the format YYYY-MM-DD:

{
"secret": "1999-07-19"
}

The response will include the status of the verification, which should now be “passed:”

{
"type": "verification",
"verification_id": "entity_27288bc122db1339",
"status": "passed"
}

Save this verification ID, it will be needed in step four.

Step 4: Log in the user#

Send a POST request to the /user/login endpoint, passing your two “passed” verification IDs in the request body:

{
"verifications": {
"type": "list",
"data": [
{
"verification_id": "entity_7d314c02e05c1221"
},
{
"verification_id": "entity_baae28af702d231f"
}
]
}
}

The response should include a user_token (user session token) you can use for future cardholder operations:

{
"type": "user_id",
"user_id": "{USER_ID}",
"user_token": "{USER_SESSION_TOKEN}"
}