Challenges v0.6.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

The Challenges API supports challenging banking users to verify their identity when performing other API operations.

This API supports challenges when the financial institution requires the user to prove their identity though a secondary challenge factor, such as entering a code sent to them via SMS (text message), email, voice call, or by answering security questions. User may have has one or more channels associated with each factor, such as a multiple phone numbers or e-mail addresses. The financial institution may require a challenge before certain actions that warrant extra validation, such as making transfers to an external institution, updating the customer's mailing address, or ordering replacement debit cards.

An API operation may return a 403 response with a challengeRequired problem type name to indicate a challenge is required for that operation. (The problem response's type is the URI https://production.api.apiture.com/errors/challengeRequired/v1.0.0/. The actual version number v1.0.0 may change, although the problem type URL always starts with https://production.api.apiture.com/errors/challengeRequired/.) For challengeRequired, the attributes in the apiProblem response lists the challenges that the client may choose from as described in the requiredIdentityChallenge schema. The user must complete one of the offered challenges.

Each challenge contains a challengeFactor which identifies how the user receives and completes the challenge. This object has a type which describes the factor used to complete the challenge and optional string labels which describe the channel(s) through which the user can complete the challenge. For sms and voice factors, the label is the last four digits of a phone number. For email challenges, the label is a masked email address. For securityQuestions, the challengeFactor includes a prompt for each of the user's security questions, and does not use the labels.

The user selects their preferred channel from those available, and the client then starts that challenge flow via the startIdentityChallenge operation. In response to that operation, the service will send an one-time passcode of several digits to the user via the corresponding channel for the sms, email, voice, authenticatorToken challenge factors. The start operation is required to activate the challenge, even if the service does not have to send information to the user, such as with securityQuestions.

The user enters the challenge response, such as the one-time passcode that was sent to them or the answers to their security questions, in the client. Then the client completes the challenge by verifying the user's challenge response.

The system verifies the submitted challenge response(s) and, if valid, returns a token that the client must pass via the Challenge request header (in conjunction with the existing Authorization header) when it retries the operation.

For example, if the user chose to complete the following sms challenge factor: { "type": "sms", "id": "15488eb31d2aef258d59", "labels": [ "3774" ] }

1. The client will start that challenge.
2. The system sends the one-time passcode such as 987303 via SMS text message to their phone ending in 3774.
3. The user enters that one-time passcode 987303 in the client application.
4. The client application submits the one-time passcode response and the corresponding challenge id (15488eb31d2aef258d59) and factor (sms) and responses using the verifyIdentityChallenge operation.

The verifyIdentityChallenge response includes a result. A result of failed means the verification failed. A result of locked means the user has failed too many verification attempts and the system has locked them out. The response also include an allows object which indicate if the user can submit new response, restart the factor (i.e. resend the one-time passcode), or try the operation again to get a new challenge.

A result of verified means the user's response matched the expected response. A response with a verified result also includes a challengeToken value. The client must send this in the Challenge request header in addition to the Authorization header when retrying the operation.

For example, if the result from verifying the response contains { ... "result": "verified", "challengeToken": "91a2a7724d6e82f5cd73", ... } and their existing bearer token is eyJraWQi...VVb1pH9bcBbg, then the client should send the request headers:

• Authentication: Bearer eyJraWQi...VVb1pH9bcBbg
• Challenge: 91a2a7724d6e82f5cd73

when retrying the operation.

Download OpenAPI Definition (YAML)

Base URLs:

• https://api.apiture.com/banking/challenges

Terms of service

Email: Apiture Web: Apiture

License: Apiture API License

Authentication

• OpenID Connect authentication (accessToken)
  • OpenId Connect (OIDC) authentication/authorization. The client uses the authorization_endpoint and token_endpoint to obtain an access token to pass in the Authorization header. Those endpoints are available via the OIDC Configuration URL. The actual URL may vary with each financial institution. See details at Secure Access.
  • OIDC Configuration URL = https://auth.apiture.com/oidc/.well-known/openid-configuration

Challenges

Challenges

startIdentityChallenge

Code samples

# You can also use wget
curl -X POST https://api.apiture.com/banking/challenges/startedChallenges \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.apiture.com/banking/challenges/startedChallenges HTTP/1.1
Host: api.apiture.com
Content-Type: application/json
Accept: application/json

const fetch = require('node-fetch');
const inputBody = '{
  "operationId": "createTransfer",
  "challengeId": "b8cae0901002bba4e2a7",
  "factor": "sms",
  "factorId": "mobile-1"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.apiture.com/banking/challenges/startedChallenges',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.apiture.com/banking/challenges/startedChallenges',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.apiture.com/banking/challenges/startedChallenges',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.apiture.com/banking/challenges/startedChallenges', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.apiture.com/banking/challenges/startedChallenges");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.apiture.com/banking/challenges/startedChallenges", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Start an identity challenge

POST https://api.apiture.com/banking/challenges/startedChallenges

Start the identity challenge flow for the user's chosen factor. For sms, voice, and email challenges, this causes the system to send a four to six digit code to the user via SMS, automated voice phone call, or email. The factor passed in the request is marked as active and eligible to be verified. The user should complete the challenge by submitting their response(s) to the challenge via the verifyIdentityChallenge operation.

Body parameter

{
  "operationId": "createTransfer",
  "challengeId": "b8cae0901002bba4e2a7",
  "factor": "sms",
  "factorId": "mobile-1"
}

Parameters

Example responses

200 Response

{
  "operationId": "createTransfer",
  "challengeId": "b8cae0901002bba4e2a7",
  "factor": "sms",
  "factorId": "mobile-1",
  "expiresAt": "2023-01-05T08:50:33.375Z",
  "minimumResponseLength": 8,
  "maximumResponseLength": 8
}

Responses

Response Schema

Status Code 400

Status Code 401

Status Code 403

Status Code 429

Status Code 4XX

Status Code 5XX

verifyIdentityChallenge

Code samples

# You can also use wget
curl -X POST https://api.apiture.com/banking/challenges/verifiedChallenges \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.apiture.com/banking/challenges/verifiedChallenges HTTP/1.1
Host: api.apiture.com
Content-Type: application/json
Accept: application/json

const fetch = require('node-fetch');
const inputBody = '{
  "factor": "securityQuestions",
  "operationId": "createTransfer",
  "factorId": "be6177eff07649128e40",
  "challengeId": "dec42c64402319a59ec7",
  "responses": [
    {
      "promptId": "q1",
      "response": "Smith"
    },
    {
      "promptId": "q4",
      "response": "Kinston High School"
    },
    {
      "promptId": "q9",
      "response": "Walter"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.apiture.com/banking/challenges/verifiedChallenges',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.apiture.com/banking/challenges/verifiedChallenges',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.apiture.com/banking/challenges/verifiedChallenges',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.apiture.com/banking/challenges/verifiedChallenges', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.apiture.com/banking/challenges/verifiedChallenges");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.apiture.com/banking/challenges/verifiedChallenges", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Verify an identity challenge

POST https://api.apiture.com/banking/challenges/verifiedChallenges

Verify an active identity challenge for a specific factor. This verifies that the submitted data matches the expected response(s) for the chosen challenge factor. The factor must be active; that is, it must be the most recent factor used to start the identity challenge.

Body parameter

{
  "factor": "securityQuestions",
  "operationId": "createTransfer",
  "factorId": "be6177eff07649128e40",
  "challengeId": "dec42c64402319a59ec7",
  "responses": [
    {
      "promptId": "q1",
      "response": "Smith"
    },
    {
      "promptId": "q4",
      "response": "Kinston High School"
    },
    {
      "promptId": "q9",
      "response": "Walter"
    }
  ]
}

Parameters

Example responses

200 Response

{
  "challengeId": "b8cae0901002bba4e2a7",
  "operationId": "createTransfer",
  "factor": "sms",
  "result": "verified",
  "challengeToken": "91a2a7724d6e82f5cd73"
}

Responses

Response Schema

Status Code 400

Status Code 401

Status Code 403

Status Code 429

Status Code 4XX

Status Code 5XX

Schemas

apiProblem

{
  "id": "3fbad566-be86-4b22-9ba6-3ca99fdc0799",
  "type": "https://production.api.apiture.com/errors/accountNotFound/v1.0.0",
  "title": "Account Not Found",
  "status": 422,
  "occurredAt": "2022-04-25T12:42:21.375Z",
  "detail": "No account exists at the given account_url",
  "instance": "https://production.api.apiture.com/banking/transfers/bb709151-575041fcd617"
}

API Problem (v1.2.1)

API problem or error, as per RFC 7807 application/problem+json.

Properties

challengeAllows

{
  "retry": true,
  "restart": true,
  "reverify": true
}

Challenge Allows (v1.0.0)

Indicates what features of the challenge are allowed after verification has failed. Note: If a retry, restart, or reverify flag is omitted, the client can call those those operations, but they may fail with a challengeBlocked error.

Properties

challengeFactor

{
  "type": "sms",
  "labels": [
    "9876"
  ]
}

Challenge Factor (v1.2.1)

An challenge factor. See requiredIdentityChallenge for multiple examples.

Properties

challengeFactorId

"string"

Challenge Factor ID (v1.0.0)

The ID of an a challenge factor. This ID is unique within the factors offered with a challenge.

type: string

minLength: 3
maxLength: 48
pattern: "^[-a-zA-Z0-9$_]{3,48}$"

challengeFactorType

"sms"

Challenge Factor Type (v1.0.0)

The name of challenge factor.

challengeFactorType strings may have one of the following enumerated values:

type: string

enum values: sms, email, voice, securityQuestions, authenticatorToken

challengeOperationId

"string"

Challenge Operation ID (v1.0.1)

The ID of an operation/action for which the user must verify their identity via an identity challenge. This is passed when starting a challenge factor or when validating the identity challenge responses.

type: string

minLength: 6
maxLength: 48
pattern: "^[-a-zA-Z0-9$_]{6,48}$"

challengePromptId

"string"

Challenge Prompt ID (v1.0.0)

The unique ID of a prompt (such as a security question) in a challenge factor.

type: string

minLength: 1
maxLength: 48
pattern: "^[-_:.~$a-zA-Z0-9]+$"

challengeResponseItem

{
  "response": "939733"
}

Challenge Response Item (v1.1.0)

A user's response to challenge.

Properties

challengeResult

"verified"

Challenge Result (v1.1.0)

The result from verifying a user's response(s) to challenge.

challengeResult strings may have one of the following enumerated values:

type: string

enum values: verified, synchronizationRequired, failed, expired, locked

challengeSecurityQuestion

{
  "id": "74699fa628911e762ea5",
  "prompt": "What is your mother's maiden name?"
}

Challenge Security Question (v1.0.1)

A single security question within the questions array of the challengeSecurityQuestions

Properties

challengeSecurityQuestions

{
  "questions": [
    {
      "id": "q1",
      "prompt": "What is your mother's maiden name?"
    },
    {
      "id": "q4",
      "prompt": "What is your high school's name?"
    },
    {
      "id": "q9",
      "prompt": "What is the name of your first pet?"
    }
  ]
}

Challenge Security Questions (v1.0.1)

Describes a securityQuestions challenge. This is omitted if the challenge type is not securityQuestions.

Properties

challengeToken

"string"

Challenge Token (v1.1.0)

The value of the identity Challenge request header that the client must send when retrying an operation which required a challenge.

type: string

minLength: 6
maxLength: 255
pattern: "^[-_:.~%$a-zA-Z0-9]{6,255}$"

identityChallenge

{
  "operationId": "createTransfer",
  "challengeId": "b8cae0901002bba4e2a7",
  "factor": "sms",
  "factorId": "mobile-1"
}

Identity Challenge (v1.3.0)

An identity challenge to verify the banking customer is who they claim.

Properties

identityChallengeResponse

{
  "factor": "securityQuestions",
  "operationId": "createTransfer",
  "factorId": "be6177eff07649128e40",
  "challengeId": "dec42c64402319a59ec7",
  "responses": [
    {
      "promptId": "q1",
      "response": "Smith"
    },
    {
      "promptId": "q4",
      "response": "Kinston High School"
    },
    {
      "promptId": "q9",
      "response": "Walter"
    }
  ]
}

Identity Challenge Response (v1.4.0)

A banking customer response(s) to an identity challenge.

Properties

problemResponse

{
  "id": "3fbad566-be86-4b22-9ba6-3ca99fdc0799",
  "type": "https://production.api.apiture.com/errors/noSuchAccount/v1.0.0",
  "title": "Account Not Found",
  "status": 422,
  "occurredAt": "2022-04-25T12:42:21.375Z",
  "detail": "No account exists for the given account reference",
  "instance": "https://production.api.apiture.com/banking/transfers/bb709151-575041fcd617"
}

Problem Response (v0.4.1)

API problem or error response, as per RFC 9457 application/problem+json.

Properties

readOnlyResourceId

"string"

Read-only Resource Identifier (v1.0.1)

The unique, opaque system-assigned identifier for a resource. This case-sensitive ID is also used in URLs as path parameters or in other properties or parameters that reference a resource by ID rather than URL. Resource IDs are immutable.

type: string

read-only
minLength: 6
maxLength: 48
pattern: "^[-_:.~$a-zA-Z0-9]{6,48}$"

readOnlyTimestamp

"2021-10-30T19:06:04.250Z"

Read-Only Timestamp (v1.0.0)

A readonly or derived timestamp (an instant in time) formatted in RFC 3339 date-time UTC format: YYYY-MM-DDThh:mm:ss.sssZ.

type: string(date-time)

read-only
format: date-time
minLength: 20
maxLength: 30

requiredIdentityChallenge

{
  "operationId": "createTransfer",
  "challengeId": "0504076c566a3cf7009c",
  "factors": [
    {
      "type": "sms",
      "labels": [
        "9876"
      ],
      "id": "85c0ee5753fcd0b0953f"
    },
    {
      "type": "voice",
      "labels": [
        "9876"
      ],
      "id": "d089e10a80a8627df37b"
    },
    {
      "type": "voice",
      "labels": [
        "6754"
      ],
      "id": "10506ecf9d1c2ee00403"
    },
    {
      "type": "email",
      "labels": [
        "an****nk@example.com",
        "an****98@example.com"
      ],
      "id": "e917d671cb2f030b56f1"
    },
    {
      "type": "authenticatorToken",
      "labels": [
        "Acme fob"
      ],
      "id": "fe6c452d7da0bbb4e407"
    },
    {
      "type": "securityQuestions",
      "securityQuestions": {
        "questions": [
          {
            "id": "q1",
            "prompt": "What is your mother's maiden name?"
          },
          {
            "id": "q4",
            "prompt": "What is your high school's name?"
          },
          {
            "id": "q9",
            "prompt": "What is the name of your first pet?"
          }
        ]
      },
      "id": "df33c6f88a37d6b3f0a6"
    }
  ]
}

Required Challenge (v1.2.3)

A request from the service for the user to verify their identity. This contains a challenge ID, the corresponding operation ID, and a list of challenge factors for identity verification. The user must complete one of these challenge factors to satisfy the challenge. This schema defines the attributes in the 401 Unauthorized problem response when the 401 problem type name is challengeRequired. See the "Challenge API" for details.

Properties

resourceId

"string"

Resource Identifier (v1.0.1)

The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.

type: string

minLength: 6
maxLength: 48
pattern: "^[-_:.~$a-zA-Z0-9]{6,48}$"

startedIdentityChallenge

{
  "operationId": "createTransfer",
  "challengeId": "b8cae0901002bba4e2a7",
  "factor": "sms",
  "factorId": "mobile-1",
  "expiresAt": "2023-01-05T08:50:33.375Z",
  "minimumResponseLength": 8,
  "maximumResponseLength": 8
}

Started Challenge (v1.4.0)

The server response after starting an identity challenge.

Properties

verifiedIdentityChallenge

{
  "challengeId": "b8cae0901002bba4e2a7",
  "operationId": "createTransfer",
  "factor": "sms",
  "result": "verified",
  "challengeToken": "91a2a7724d6e82f5cd73"
}

Verified Challenge (v1.4.0)

The response from verifying the challenge.

Properties