Shell HTTP JavaScript Node.JS Ruby Python Java Go

Auth v0.13.1

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

Introduction

The Authentication API is an identity layer based on OpenID Connect (OIDC) and OAuth 2.0. Accessing resources in the Apiture Open platform requires registering an OAuth consumer before making authenticated API requests.

Discovery

The OpenID Connect Discovery metadata can be retrieved by browsing to the /auth/openid/metadata URL. The metadata information is public.

Creating a consumer

Request an OAuth consumer key and secret by emailing api@apiture.com. The following information must be part of the consumer request:

After submitting the request, an email will be sent containing the generated key and secret for the consumer.

Flows

Supported authentication flows

OpenID Connect Authorization Code Flow

This interactive flow involves browser redirection to the Apiture Identity Provider URL (the OAuth authorization server) for secure user login and consent. After the first redirection, the user is redirected back to the requesting application using the callback URL that was configured when the application was registered as a consumer.

  1. Authenticate the user [browser redirection]
  2. Receive user consent [browser redirection]
  3. Authenticate the client
  4. Exchange code for tokens

OpenID Connect Implicit Flow

This flow is similar to the code flow but allows to retrieve a token directly without the need of an intermediate code. Upon successful authentication the tokens are returned in the hash fragment of the redirection URL. No refresh tokens are returned using this type of grant.

  1. Authenticate the user [browser redirection]
  2. Receive user consent [browser redirection]

More information about triggering these flows can be found by reading about the /auth/oauth2 endpoints below.

Using the Tokens

Upon successful authentication the token endpoint will return an access token that can be used to call secured API endpoints, it will have an expiration time in milliseconds as indicated in the expires_in attribute.

Each request to a secured endpoint must include the bearer token as part of the Authorization header: Authorization: Bearer <TOKEN> The /oauth2/token#refreshToken endpoint can be used to refresh an expired token. To do this the grant_type must be set to refresh_token and the refresh_token parameter must be the refresh token obtained when the last token was issued.

Password reset flow

It is possible to reset the user's password from an unauthenticated space by sending the user's key identifying information.

  1. Start the process by issuing a POST to /passwordResetRequests with the user's username, taxId and birthdate. A confirmation code is sent via the preconfigured delivery channel as a result of this operation.
  2. Use the confirmation code as part of a POST request to /passwordResets along with the user's username and the new desired password. A successful password reset will be acknowledged with a 202 status code.

Devices

For additional security, this API also manages the devices (such as cell phones, tablets, computers) that the user uses for digital banking. This allows the Apiture platform to notify the user if someone logs onto their account from an unknown device. Each device has a unique device ID.

Device management improves the multi-factor authentication (MFA) experience for users. If SMS-based MFA is enabled, end users must input a security code received via SMS in addition to entering their password during every sign-in . With device management, users can specify that a device is trusted and the authentication service will remember the device as trusted. Trusted devices can serve as a second factor of authentication instead of requiring a security code delivered via SMS.

This feature tracks each device/user combination separately, such as a husband and wife logging onto digital banking on a shared laptop or table. If the husband has chosen to trust the device, he may sign in using the device and not have to use secondary authentication such as an code sent via SMS. If the wife has not marked the device as trusted, when they sign in, they will need to use the secondary authentication such as an code sent via SMS.

A financial institution can disable tracking of trusted devices so that other secondary authentication such as SMS codes or biometrics must be used on each sign in.

Identity Challenges

The Challenges and Authenticator operations support additional user identity verification challenges to allow a user to verify they are who they claim to be, such as entering a code send via email or SMS. A challenge represents a resource for tracking this additional authentication.

For example, in the Users API, when a user tries to change their preferred mailing address, email address, or phone number, the operations may require an additional identity verification challenge. This helps prevent fraudulent use if someone gains access to an account and attempts to take it over without the owner's consent or knowledge by changing the account's contact information. Other APIs which may use the Challenge API include the Transfers API to confirm identity before transferring money higher than some user-level transfer threshold or much higher than historical transfers, or the Accounts API when adding or removing joint owners or authorized signers.

API services initiate challenges when required. If an operation requires a challenge, the initial operation fails with a 401 Unauthorized response with an _error object in the response. That error response has the error type of identityChallengeRequired. The error object contains a _embedded.challenge object which describes the challenge (see the challengeErrorResponse schema).

A challenge consists of:

An authenticator contains

For example, a type may be sms which means the authenticator will send an SMS message to the user's mobile device; the message contains a code (4 to 6 digits) which the user must enter in the application. The schema attached to sms will list the preferred mobile device number(s) for the user or account, and perhaps other allowed mobile device phone numbers. Other types include email (a similar code is sent to the user at the preferred email address.) Clients must be prepared to handle all the authenticator types.

The client should start the selected authenticators by using a POST to their apiture:start links (operation startAuthenticator). For example, for sms and email authenticator types, the service will send a code to the user's preferred mobile phone number or email address respectively. The type in the authenticator includes a JSON schema which describes the data that should be passed in the authenticator's attributes. The client should collect data from the user and then post the authenticator resource (with the user data in the attributes) to the verifyAuthenticator operation. This validates the data and either completes the authenticator (and challenge) or fails.

After the required authenticators are verified and the challenge has been completed, the client application should retry the initial operation that failed with the 401 error. The client should pass the _id of the challenge resource in the Apiture-Challenge request header on this operation retry. Operations which participate in the Challenge protocol will document the optional Apiture-Challenge request header as one of the operation's parameters.

Challenges and authenticators expire and they are automatically deleted after a delay of several minutes.

Session Tracking

You may use the Authentication API to track user sessions. There are operations to mark the beginning, continuation, and ending of a user session (log on, refresh a user's access token, log off). See the startUserSession, continueUserSession, endUserSession operations.

Download OpenAPI Definition (YAML)

Base URLs:

Terms of service

Email: Apiture Web: Apiture

Authentication

Scope Scope Description
profiles/read Read access to user and contact related resources.
profiles/write Write (update) access to user and contact related resources.
profiles/delete Delete access to user and auth related resources.
profiles/readPii Read access to personally identifiable information such as tax ID numbers, phone numbers, email and postal addresses. This must be granted in addition to the profiles/read scope in order to read such data, but is included in the profiles/full scope.
profiles/full Full access to user and contact related resources.
admin/write Admin write (update) access to challenges and authenticators

Discovery

OpenID Connect Discovery

getMetadata

Code samples

# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/openid/metadata \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

GET https://api.devbank.apiture.com/auth/openid/metadata HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/json

var headers = {
  'Accept':'application/json',
  'API-Key':'API_KEY'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/openid/metadata',
  method: 'get',

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

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'API-Key':'API_KEY'

};

fetch('https://api.devbank.apiture.com/auth/openid/metadata',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'API-Key' => 'API_KEY'
}

result = RestClient.get 'https://api.devbank.apiture.com/auth/openid/metadata',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'API-Key': 'API_KEY'
}

r = requests.get('https://api.devbank.apiture.com/auth/openid/metadata', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/openid/metadata");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
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{
        "Accept": []string{"application/json"},
        "API-Key": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/openid/metadata", data)
    req.Header = headers

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

Returns OpenID Connect Discovery metadata.

GET /openid/metadata

This request returns a JSON structure containing scopes.

Try It

Example responses

200 Response

{}

400 Response

Responses

StatusDescription
200 OK
The metadata was returned successfully.
Schema: authMetadata
StatusDescription
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
422 Unprocessable Entity
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The _error field in the response will contain details about the request error.
Schema: errorResponse

Authorize

User authentication and authorization

authorize

Code samples

# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/oauth2/authorize?client_id=string \
  -H 'Accept: */*' \
  -H 'API-Key: API_KEY'

GET https://api.devbank.apiture.com/auth/oauth2/authorize?client_id=string HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*

var headers = {
  'Accept':'*/*',
  'API-Key':'API_KEY'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/oauth2/authorize',
  method: 'get',
  data: '?client_id=string',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'*/*',
  'API-Key':'API_KEY'

};

fetch('https://api.devbank.apiture.com/auth/oauth2/authorize?client_id=string',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => '*/*',
  'API-Key' => 'API_KEY'
}

result = RestClient.get 'https://api.devbank.apiture.com/auth/oauth2/authorize',
  params: {
  'client_id' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': '*/*',
  'API-Key': 'API_KEY'
}

r = requests.get('https://api.devbank.apiture.com/auth/oauth2/authorize', params={
  'client_id': 'string'
}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/oauth2/authorize?client_id=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
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{
        "Accept": []string{"*/*"},
        "API-Key": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/oauth2/authorize", data)
    req.Header = headers

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

Redirect to id.apiture.com for secure user login

GET /oauth2/authorize

This request redirects the user to the Apiture Identity Provider login page.

Parameters

Parameter Description
response_type
(query)
string
Indicates the authentication flow to be used. Use code to specify the usage of the OAuth 2.0 Authorization code flow and token for the OAuth 2.0 implicit grant flow.
scope
(query)
string
This must be set to openid to indicate a request for OpenID authentication and ID token.
client_id
(query)
string (required)
This must be set to the key obtained after registration of the application as a consumer.
state
(query)
string
An arbitrary value set by the client to maintain state between the authorization request and the callback.
redirect_uri
(query)
string
The callback url that the user will be redirected to after successful login and consent with the Apiture Identity Provider. This value must match the value used during the consumer registration process. The callback url will be called with the authorization code provided as a parameter. Required if using the authorization_code flow.

Try It

Example responses

400 Response

Responses

StatusDescription
302 Found
Indicates a redirection url has been returned to the client.
StatusDescription
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
422 Unprocessable Entity
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The _error field in the response will contain details about the request error.
Schema: errorResponse

Response Headers

StatusDescription
302 Location string
The login and consent page of the Apiture Identity Provider.

Devices

User devices

getDevices

Code samples

# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/users/{userId}/devices \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.devbank.apiture.com/auth/users/{userId}/devices HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/json

var headers = {
  'Accept':'application/json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/users/{userId}/devices',
  method: 'get',

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

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/users/{userId}/devices',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.devbank.apiture.com/auth/users/{userId}/devices',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.devbank.apiture.com/auth/users/{userId}/devices', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/users/{userId}/devices");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
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{
        "Accept": []string{"application/json"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/users/{userId}/devices", data)
    req.Header = headers

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

Return a collection of devices

GET /users/{userId}/devices

Return a collection of devices that the user has used to sign in. This collection is small, so this operation does not support filtering, pagination, sorting, or searching. The Authentication API's getRoot operation (GET /auth/) will include a link apiture:getDevices. This link's href will resolve the {userId} for the currently authenticated user.

Parameters

Parameter Description
userId
(path)
string (required)
The user ID of a user. An authenticated user can only view their own devices.

Try It

Example responses

200 Response

{
  "_profile": "https://api.apiture.com/schemas/auth/devices/v1.0.0/profile.json",
  "start": 0,
  "limit": 100,
  "count": 1,
  "name": "devices",
  "_links": {
    "collection": {
      "href": "/auth/users/testUser/devices"
    }
  },
  "_embedded": {
    "items": [
      {
        "_profile": "https://api.apiture.com/schemas/auth/device/v1.0.0/profile.json",
        "_id": "us-east-1_b6530c4c-572a-403a-9452-cd0c74c715a1",
        "name": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
        "lastIpAddress": "34.198.94.30",
        "trusted": false,
        "lastLoggedInAt": "2019-06-25T11:48:18.000Z",
        "userId": "testUser"
      }
    ]
  }
}

403 Response

Responses

StatusDescription
200 OK
OK
Schema: Inline
StatusDescription
403 Forbidden
The client is not authorized to generate a new token.
Schema: errorResponse
StatusDescription
404 Not Found
The device was not found. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
429 Too Many Requests
Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP will be blocked from further requests until a period of time has passed.
Schema: errorResponse
StatusDescription
500 Internal Server Error
Server Error. Fatal error has occurred.
Schema: errorResponse

Response Schema

Status Code 200

Property Name Description
» _links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
»» Link link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
»»» href string(uri) (required)
The URI or URI template for the resource/operation this link refers to.
»»» type string
The media type for the resource.
»»» templated boolean
If true, the link's href is a URI template.
»»» title string
An optional human-readable localized title for the link.
»»» deprecation string(uri)
If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.
»»» profile string(uri)
The URI of a profile document, a JSON document which describes the target resource/operation.
»» _embedded object
Embedded device objects.
»»» items [device]
An array of devices which user uses to sign in.
»»»» Device device
A device which the user has used to sign in to digital banking.
»»»»» _links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
»»»»» _embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
»»»»» _profile string(uri)
The URI of a resource profile which describes the representation.
»»»»» _error error
An object which describes an error. This value is omitted if the operation succeeded without error.
»»»»»» message string (required)
A localized message string describing the error condition.
»»»»»» _id string
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string.
»»»»»» statusCode integer
The HTTP status code associate with this error.
minimum: 100
maximum: 599
»»»»»» type string
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode. For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet.
»»»»»» occurredAt string(date-time)
An RFC 3339 UTC time stamp indicating when the error occurred.
»»»»»» attributes attributes
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type.
»»»»»»» Attribute Value attributeValue
The data associated with this attribute.
»»»»»» remediation string
An optional localized string which provides hints for how the user or client can resolve the error.
»»»»»» errors [error]
An optional array of nested error objects. This property is not always present.
»»»»»»» Error error
Describes an error in an API request or in a service called via the API.
»»»»»»»» message string (required)
A localized message string describing the error condition.
»»»»»»»» _id string
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string.
»»»»»»»» statusCode integer
The HTTP status code associate with this error.
minimum: 100
maximum: 599
»»»»»»»» type string
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode. For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet.
»»»»»»»» occurredAt string(date-time)
An RFC 3339 UTC time stamp indicating when the error occurred.
»»»»»»»» attributes attributes
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type.
»»»»»»»»» Attribute Value attributeValue
The data associated with this attribute.
»»»»»»»» remediation string
An optional localized string which provides hints for how the user or client can resolve the error.
»»»»»»»» errors [error]
An optional array of nested error objects. This property is not always present.
»»»»»»»» _links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
»»»»»»» _links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
»»»»»» _id string
The device unique identifier.
»»»»»» operatingSystem string
The operating system of the device, if known. iOS, Android, macOS, Windows, Linux are examples. An empty or omitted value indicates the value could not be determined.
maxLength: 16
»»»»»» vendor string
The vendor of the device, if known. Apple, Google, Samsung, LG are examples. An empty or omitted value indicates the value could not be determined.
maxLength: 16
»»»»»» secondaryId string
An additional unique host-defined device identifier, for example a unique ID for advertising or other purposes.
»»»»»» name string
The name of the device, derived from the authentication flow.
»»»»»» type string
The type (category) of the device, if known. 'mobile', 'desktop' are examples. An empty or omitted value indicates the value could not be determined.
maxLength: 16
»»»»»» lastIpAddress string
The IP address used when the user last logged in with this device.
»»»»»» trusted boolean
If true, the user indicated that the device is trusted when signing in on the device. Future sign ins on the device will not require alternate multi-factor authentication such as entering a code sent by the financial institution via SMS. If false, the user has not indicated the specific device is trusted.
»»»»»» lastLoggedInAt string(date-time)
The timestamp of last login. This is in RFC 3339 format, YYYY-MM-DDThh:mm:ss.sssZ
»»»»»» userId string
The user identified by userId.
»»»»» _profile string(uri)
The URI of a resource profile which describes the representation.
»»»»» _error error
An object which describes an error. This value is omitted if the operation succeeded without error.
»»»»»» message string (required)
A localized message string describing the error condition.
»»»»»» _id string
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string.
»»»»»» statusCode integer
The HTTP status code associate with this error.
minimum: 100
maximum: 599
»»»»»» type string
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode. For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet.
»»»»»» occurredAt string(date-time)
An RFC 3339 UTC time stamp indicating when the error occurred.
»»»»»» attributes attributes
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type.
»»»»»»» Attribute Value attributeValue
The data associated with this attribute.
»»»»»» remediation string
An optional localized string which provides hints for how the user or client can resolve the error.
»»»»»» errors [error]
An optional array of nested error objects. This property is not always present.
»»»»»» _links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
»»»»» count integer
The number of items in the collection. This value is optional and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter.
»»»»» start integer
The start index of this page of items.
»»»»» limit integer
The maximum number of items per page.
»»»»» name string
The name of the collection.

getDevice

Code samples

# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId} \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId} HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/json

var headers = {
  'Accept':'application/json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}',
  method: 'get',

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

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
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{
        "Accept": []string{"application/json"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}", data)
    req.Header = headers

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

Return a device for the user

GET /users/{userId}/devices/{deviceId}

Return a specific device for a user. The deviceId is the unique identifier of a device resource. This operation is typically called via the self link for an item in the getDevices collection response.

Parameters

Parameter Description
userId
(path)
string (required)
The user ID of a user. An authenticated user can only view their own devices.
deviceId
(path)
string (required)
The unique identifier of the device.

Try It

Example responses

200 Response

{
  "_profile": "https://api.apiture.com/schemas/auth/device/v1.0.0/profile.json",
  "_id": "us-east-1_b6530c4c-572a-403a-9452-cd0c74c715a1",
  "name": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
  "lastIpAddress": "34.198.94.30",
  "trusted": false,
  "lastLoggedInAt": "2019-06-25T11:48:18.000Z",
  "userId": "testUser"
}

403 Response

Responses

StatusDescription
200 OK
OK
Schema: Inline
StatusDescription
403 Forbidden
The client is not authorized to generate a new token.
Schema: errorResponse
StatusDescription
404 Not Found
The device was not found. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
429 Too Many Requests
Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP will be blocked from further requests until a period of time has passed.
Schema: errorResponse
StatusDescription
500 Internal Server Error
Server Error. Fatal error has occurred.
Schema: errorResponse

Response Schema

Status Code 200

Property Name Description
» _links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
»» Link link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.
»»» href string(uri) (required)
The URI or URI template for the resource/operation this link refers to.
»»» type string
The media type for the resource.
»»» templated boolean
If true, the link's href is a URI template.
»»» title string
An optional human-readable localized title for the link.
»»» deprecation string(uri)
If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.
»»» profile string(uri)
The URI of a profile document, a JSON document which describes the target resource/operation.
»» _embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
»» _profile string(uri)
The URI of a resource profile which describes the representation.
»» _error error
An object which describes an error. This value is omitted if the operation succeeded without error.
»»» message string (required)
A localized message string describing the error condition.
»»» _id string
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string.
»»» statusCode integer
The HTTP status code associate with this error.
minimum: 100
maximum: 599
»»» type string
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode. For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet.
»»» occurredAt string(date-time)
An RFC 3339 UTC time stamp indicating when the error occurred.
»»» attributes attributes
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type.
»»»» Attribute Value attributeValue
The data associated with this attribute.
»»» remediation string
An optional localized string which provides hints for how the user or client can resolve the error.
»»» errors [error]
An optional array of nested error objects. This property is not always present.
»»»» Error error
Describes an error in an API request or in a service called via the API.
»»»»» message string (required)
A localized message string describing the error condition.
»»»»» _id string
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string.
»»»»» statusCode integer
The HTTP status code associate with this error.
minimum: 100
maximum: 599
»»»»» type string
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode. For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet.
»»»»» occurredAt string(date-time)
An RFC 3339 UTC time stamp indicating when the error occurred.
»»»»» attributes attributes
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type.
»»»»»» Attribute Value attributeValue
The data associated with this attribute.
»»»»» remediation string
An optional localized string which provides hints for how the user or client can resolve the error.
»»»»» errors [error]
An optional array of nested error objects. This property is not always present.
»»»»» _links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
»»»» _links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
»»» _id string
The device unique identifier.
»»» operatingSystem string
The operating system of the device, if known. iOS, Android, macOS, Windows, Linux are examples. An empty or omitted value indicates the value could not be determined.
maxLength: 16
»»» vendor string
The vendor of the device, if known. Apple, Google, Samsung, LG are examples. An empty or omitted value indicates the value could not be determined.
maxLength: 16
»»» secondaryId string
An additional unique host-defined device identifier, for example a unique ID for advertising or other purposes.
»»» name string
The name of the device, derived from the authentication flow.
»»» type string
The type (category) of the device, if known. 'mobile', 'desktop' are examples. An empty or omitted value indicates the value could not be determined.
maxLength: 16
»»» lastIpAddress string
The IP address used when the user last logged in with this device.
»»» trusted boolean
If true, the user indicated that the device is trusted when signing in on the device. Future sign ins on the device will not require alternate multi-factor authentication such as entering a code sent by the financial institution via SMS. If false, the user has not indicated the specific device is trusted.
»»» lastLoggedInAt string(date-time)
The timestamp of last login. This is in RFC 3339 format, YYYY-MM-DDThh:mm:ss.sssZ
»»» userId string
The user identified by userId.

deleteDevice

Code samples

# You can also use wget
curl -X DELETE https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId} \
  -H 'Accept: */*' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

DELETE https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId} HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*

var headers = {
  'Accept':'*/*',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}',
  method: 'delete',

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

const fetch = require('node-fetch');

const headers = {
  'Accept':'*/*',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => '*/*',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete 'https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': '*/*',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
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{
        "Accept": []string{"*/*"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}", data)
    req.Header = headers

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

Delete a device registration

DELETE /users/{userId}/devices/{deviceId}

Delete a specific device registration which tracks the use of a device for a user. Once deleted, the user will have to use another secondary authentication method, such as entering a code sent by SMS, when signing in.

Parameters

Parameter Description
userId
(path)
string (required)
The user ID of a user. An authenticated user can only view their own devices.
deviceId
(path)
string (required)
The unique identifier of the device.

Try It

Example responses

403 Response

Responses

StatusDescription
204 No Content
No Content. The resource was deleted successfully.
StatusDescription
403 Forbidden
The client is not authorized to generate a new token.
Schema: errorResponse
StatusDescription
404 Not Found
The device was not found. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
429 Too Many Requests
Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP will be blocked from further requests until a period of time has passed.
Schema: errorResponse
StatusDescription
500 Internal Server Error
Server Error. Fatal error has occurred.
Schema: errorResponse

User Sessions

User Session Life Cycles

startUserSession

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/userSession \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.devbank.apiture.com/auth/userSession HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*

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

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/userSession',
  method: 'post',

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

const fetch = require('node-fetch');
const inputBody = '{
  "_profile": "https://api.apiture.com/auth/userSessionStart/v1.0.0/model.json",
  "mfa": {
    "performed": true,
    "tryCount": 1
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

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

require 'rest-client'
require 'json'

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

result = RestClient.post 'https://api.devbank.apiture.com/auth/userSession',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.post('https://api.devbank.apiture.com/auth/userSession', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/userSession");
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{"*/*"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

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

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

POST /userSession

Start a user's virtual session. Clients should call this to mark when a user logs in. This operation is not required, but using it allows the financial institution to monitor and audit users' sessions and help prevent fraudulent use. The operation returns a session identifer which the client should pass to continue or complete the session with the continueUserSession and endUserSession operations. The response contains links to these operations. The response for this operation is also passed directly to those other operations.

This operation is idempotent. If the session has already been started, this operation returns that session.

Body parameter

{
  "_profile": "https://api.apiture.com/auth/userSessionStart/v1.0.0/model.json",
  "mfa": {
    "performed": true,
    "tryCount": 1
  }
}

Parameters

Parameter Description
body
(body)
userSessionStart (required)
Client information for tracking the session.

Try It

Example responses

202 Response

Responses

StatusDescription
202 Accepted
Accepted
Schema: userSession
StatusDescription
400 Bad Request
Bad Request. The request body is badly formed or contains invalid data.
Schema: #/components/responses/400
StatusDescription
422 Unprocessable Entity
Unprocessable Entity. An aspect of the request was well formed but otherwise invalid. The _error field in the response will contain details about the request error.
Schema: #/components/responses/422UserSessionStart

continueUserSession

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/continuedUserSessions \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.devbank.apiture.com/auth/continuedUserSessions HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*

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

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/continuedUserSessions',
  method: 'post',

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

const fetch = require('node-fetch');
const inputBody = '{
  "_profile": "https://api.apiture.com/auth/userSession/v1.0.0/model.json",
  "_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

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

require 'rest-client'
require 'json'

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

result = RestClient.post 'https://api.devbank.apiture.com/auth/continuedUserSessions',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.post('https://api.devbank.apiture.com/auth/continuedUserSessions', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/continuedUserSessions");
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{"*/*"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

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

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

POST /continuedUserSessions

Continue a session. After the client refreshes the user's access token, it may post the user session to this path to indicate that it wishes to continue the virtual session, but associated with the new token. The client must call this operation with the new access token in the Authorization header.

This operation is idempotent. If the session has already been continued, this operation returns that session.

Body parameter

{
  "_profile": "https://api.apiture.com/auth/userSession/v1.0.0/model.json",
  "_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}

Parameters

Parameter Description
body
(body)
userSession (required)
Client information for tracking the continuing user session. This is the userSession returned from either the startUserSession operation or from the most recent call to continueUserSession for this user, whichever was most recent.

Try It

Example responses

202 Response

Responses

StatusDescription
202 Accepted
Accepted. The client should pass the response from this operation to the next call to continueUserSession after the current token is refreshed, or to the endUserSession operation
Schema: userSession
StatusDescription
400 Bad Request
Bad Request. The request body is badly formed or contains invalid data.
Schema: #/components/responses/400
StatusDescription
404 Not Found
Not Found. The session does not exist. This error may also occur if the session has already been ended.
Schema: #/components/responses/400

endUserSession

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/completedSessions \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.devbank.apiture.com/auth/completedSessions HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*

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

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/completedSessions',
  method: 'post',

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

const fetch = require('node-fetch');
const inputBody = '{
  "_profile": "https://api.apiture.com/auth/userSession/v1.0.0/model.json",
  "_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

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

require 'rest-client'
require 'json'

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

result = RestClient.post 'https://api.devbank.apiture.com/auth/completedSessions',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.post('https://api.devbank.apiture.com/auth/completedSessions', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/completedSessions");
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{"*/*"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

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

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

POST /completedSessions

End a user session. When the client wishes to end a user session, it can call this operation to inform the platform. The client may use an explicit logout operation, or it may end a session after a period of inactivity.

Upon ending a user session, the client should purge any local cached data associated with the user and discard their access token and the userSession object.

Body parameter

{
  "_profile": "https://api.apiture.com/auth/userSession/v1.0.0/model.json",
  "_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}

Parameters

Parameter Description
body
(body)
userSession (required)
Client information for tracking the current user session. This is the userSession returned from either the startSession operation or from the most recent call to continueSession for this user, whichever was most recent.

Try It

Example responses

400 Response

Responses

StatusDescription
204 No Content
No Content
StatusDescription
400 Bad Request
Bad Request. The request body is badly formed or contains invalid data.
Schema: #/components/responses/400
StatusDescription
404 Not Found
Not Found. The user session does not exist. This error may also occur if the user session has already been ended.
Schema: #/components/responses/400

API

The Authentication API

getApi

Code samples

# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/ \
  -H 'Accept: application/hal+json'

GET https://api.devbank.apiture.com/auth/ HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/hal+json

var headers = {
  'Accept':'application/hal+json'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/',
  method: 'get',

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

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/hal+json'

};

fetch('https://api.devbank.apiture.com/auth/',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/hal+json'
}

result = RestClient.get 'https://api.devbank.apiture.com/auth/',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/hal+json'
}

r = requests.get('https://api.devbank.apiture.com/auth/', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
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{
        "Accept": []string{"application/hal+json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/", data)
    req.Header = headers

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

Top-level resources and operations in this API

GET /

Return links to the top-level resources and operations in this API.

Try It

Example responses

OK

{
  "id": "auth",
  "name": "Authorization",
  "apiVersion": "0.1.0",
  "_profile": "https://api.apiture.com/schemas/common/root/v2.0.0/profile.json",
  "_links": {
    "apiture:authorize": {
      "href": "/auth/oauth2/authorize"
    },
    "apiture:token": {
      "href": "/auth/oauth2/token"
    },
    "apiture:metadata": {
      "href": "/auth/openid/metadata"
    }
  }
}

200 Response

{
  "id": "apiName",
  "name": "API name",
  "apiVersion": "1.0.0",
  "_profile": "https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json",
  "_links": {}
}

Responses

StatusDescription
200 OK
OK
Schema: root

getApiDoc

Code samples

# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/apiDoc \
  -H 'Accept: application/json'

GET https://api.devbank.apiture.com/auth/apiDoc HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/json

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/apiDoc',
  method: 'get',

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

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://api.devbank.apiture.com/auth/apiDoc',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.devbank.apiture.com/auth/apiDoc',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.devbank.apiture.com/auth/apiDoc', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/apiDoc");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
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{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/apiDoc", data)
    req.Header = headers

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

Return API definition document

GET /apiDoc

Return the OpenAPI document that describes this API.

Try It

Example responses

200 Response

{}

Responses

StatusDescription
200 OK
OK
Schema: Inline

Response Schema

Token

getToken

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/oauth2/token \
  -H 'Accept: application/json' \
  -H 'Authorization: string' \
  -H 'API-Key: API_KEY'

POST https://api.devbank.apiture.com/auth/oauth2/token HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/json
Authorization: string

var headers = {
  'Accept':'application/json',
  'Authorization':'string',
  'API-Key':'API_KEY'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/oauth2/token',
  method: 'post',

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

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'string',
  'API-Key':'API_KEY'

};

fetch('https://api.devbank.apiture.com/auth/oauth2/token',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'string',
  'API-Key' => 'API_KEY'
}

result = RestClient.post 'https://api.devbank.apiture.com/auth/oauth2/token',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'string',
  'API-Key': 'API_KEY'
}

r = requests.post('https://api.devbank.apiture.com/auth/oauth2/token', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/oauth2/token");
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{
        "Accept": []string{"application/json"},
        "Authorization": []string{"string"},
        "API-Key": []string{"API_KEY"},
        
    }

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

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

Obtain a secure access token.

POST /oauth2/token

Create an access token for client use. The authorization code received from the callback redirection is an intermediate credential. The code must then be exchanged with a token by making a request to this endpoint.

Parameters

Parameter Description
Authorization
(header)
string (required)
Authorization credentials in the form of

Basic <ENCODED-CREDENTIALS>

where <ENCODED-CREDENTIALS> is a base 64 encoding of the text key:secret for the registered client. If these client credentials are supplied when using the client_credentials grant, the OpenID Connect handshake is shortened and no interactive redirect is used. This form of authentication is less secure since it requires transmitting credentials. This should only be used with trusted clients.

grant_type
(query)
string
This must be set to one of the following:
  1. authorization_code if using the OAuth 2.0 Authorization code flow
  2. client_credentials when using client-supplied credentials (key and secret)
  3. refresh_token when refreshing an expired token. | |code
    (query) | string
    This must be set to the authorization code returned via a callback redirect after calling the /auth/oauth2/authorize endpoint if using the OAuth 2.0 Authorization code flow. | |redirect_uri
    (query) | string
    The callback url that the user will be redirected to after successful login and consent with the Apiture Identity Provider. This value must match the value used during the consumer registration process. The callback url will be called with the authorization code provided as a parameter. Required if using the authorization_code flow. |

Try It

Example responses

200 Response

{
  "access_token": "string",
  "token_type": "string",
  "expires_in": 0,
  "refresh_token": "string"
}

400 Response

Responses

StatusDescription
200 OK
Return a response containing the access token, refresh token, etc.
Schema: oauthToken
StatusDescription
302 Found
Indicates a redirection url has been returned to the client.
StatusDescription
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
401 Unauthorized
The client did not include credentials or the credentials are not valid, or the access_token has expired and should be refreshed.
Schema: errorResponse
StatusDescription
403 Forbidden
The client is not authorized to generate a new token.
Schema: errorResponse
StatusDescription
422 Unprocessable Entity
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The _error field in the response will contain details about the request error.
Schema: errorResponse

Response Headers

StatusDescription
302 Location string
The login and consent page of the Apiture Identity Provider.

refreshToken

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/oauth2/token#refreshToken?refresh_token=string \
  -H 'Accept: application/json' \
  -H 'Authorization: string' \
  -H 'API-Key: API_KEY'

POST https://api.devbank.apiture.com/auth/oauth2/token#refreshToken?refresh_token=string HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/json
Authorization: string

var headers = {
  'Accept':'application/json',
  'Authorization':'string',
  'API-Key':'API_KEY'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/oauth2/token#refreshToken',
  method: 'post',
  data: '?refresh_token=string',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'string',
  'API-Key':'API_KEY'

};

fetch('https://api.devbank.apiture.com/auth/oauth2/token#refreshToken?refresh_token=string',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'string',
  'API-Key' => 'API_KEY'
}

result = RestClient.post 'https://api.devbank.apiture.com/auth/oauth2/token#refreshToken',
  params: {
  'refresh_token' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'string',
  'API-Key': 'API_KEY'
}

r = requests.post('https://api.devbank.apiture.com/auth/oauth2/token#refreshToken', params={
  'refresh_token': 'string'
}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/oauth2/token#refreshToken?refresh_token=string");
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{
        "Accept": []string{"application/json"},
        "Authorization": []string{"string"},
        "API-Key": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/oauth2/token#refreshToken", data)
    req.Header = headers

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

Obtain new tokens after an access token has expired.

POST /oauth2/token#refreshToken

Create a new access token for client use after an access_token has expired.

Parameters

Parameter Description
Authorization
(header)
string (required)
Authorization credentials in the form of

Basic <ENCODED-CREDENTIALS>

where <ENCODED-CREDENTIALS> is a base 64 encoding of the text key:secret for the registered client. If these client credentials are supplied when using the client_credentials grant, the OpenID Connect handshake is shortened and no interactive redirect is used. This form of authentication is less secure since it requires transmitting credentials. This should only be used with trusted clients.

grant_type
(query)
string
This must be set to one of the following:
  1. authorization_code if using the OAuth 2.0 Authorization code flow
  2. client_credentials when using client-supplied credentials (key and secret)
  3. refresh_token when refreshing an expired token. | |refresh_token
    (query) | string (required)
    The value of the refresh_token obtained with the original expired access token. |

Try It

Example responses

200 Response

{
  "access_token": "string",
  "token_type": "string",
  "expires_in": 0,
  "refresh_token": "string"
}

400 Response

Responses

StatusDescription
200 OK
Return a response containing the new access token, refresh token, etc.
Schema: oauthToken
StatusDescription
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
401 Unauthorized
The client did not include credentials or the credentials are not valid, or the access_token has expired and should be refreshed.
Schema: errorResponse
StatusDescription
403 Forbidden
The client is not authorized to generate a new token.
Schema: errorResponse
StatusDescription
422 Unprocessable Entity
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The _error field in the response will contain details about the request error.
Schema: errorResponse

User

usernameRequests

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/usernameRequests \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

POST https://api.devbank.apiture.com/auth/usernameRequests HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: application/json

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'API-Key':'API_KEY'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/usernameRequests',
  method: 'post',

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

const fetch = require('node-fetch');
const inputBody = '{
  "lastName": "Smith",
  "taxId": "1234",
  "birthdate": "1975-02-28"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'API-Key':'API_KEY'

};

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

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'API-Key' => 'API_KEY'
}

result = RestClient.post 'https://api.devbank.apiture.com/auth/usernameRequests',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'API-Key': 'API_KEY'
}

r = requests.post('https://api.devbank.apiture.com/auth/usernameRequests', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/usernameRequests");
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"},
        "API-Key": []string{"API_KEY"},
        
    }

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

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

Request sending the user an email containing their forgotten username.

POST /usernameRequests

Request sending the user an email containing their forgotten username by submitting the user's key identifying information. (This operation does not create a resource.) An email containing the username is sent to the user as a result of this operation.

Body parameter

{
  "lastName": "Smith",
  "taxId": "1234",
  "birthdate": "1975-02-28"
}

Parameters

Parameter Description
body
(body)
usernameRequest (required)
The data necessary to request the user's username be sent to them.

Try It

Example responses

202 Response

{
  "lastName": "Smith",
  "taxId": "1234",
  "birthdate": "1975-02-28"
}

422 Response

Responses

StatusDescription
202 Accepted
Accepted
Schema: usernameRequestNotification
StatusDescription
422 Unprocessable Entity
Username request is invalid.
Schema: errorResponse
StatusDescription
429 Too Many Requests
Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP will be blocked from further requests until a period of time has passed.
Schema: errorResponse

confirmUser

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/confirmedUsers \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'API-Key: API_KEY'

POST https://api.devbank.apiture.com/auth/confirmedUsers HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*

var headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'API-Key':'API_KEY'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/confirmedUsers',
  method: 'post',

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

const fetch = require('node-fetch');
const inputBody = '{
  "_profile": "https://api.apiture.com/schemas/users/userConfirmation/v1.0.0/model.json",
  "firstName": "John",
  "lastName": "Smith",
  "birthdate": {},
  "taxId": "112-22-3333"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'API-Key':'API_KEY'

};

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

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => '*/*',
  'API-Key' => 'API_KEY'
}

result = RestClient.post 'https://api.devbank.apiture.com/auth/confirmedUsers',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': '*/*',
  'API-Key': 'API_KEY'
}

r = requests.post('https://api.devbank.apiture.com/auth/confirmedUsers', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/confirmedUsers");
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{"*/*"},
        "API-Key": []string{"API_KEY"},
        
    }

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

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

Convert a user to new digital banking platform

POST /confirmedUsers

After enabling the Apiture platform and importing customers from the banking core, a client application can use this operation to confirm and create a user's login account. The client application should prompt the user for their first and last name, date of birth, and tax identification number (such as a social security number) and submit the data here. A successful operation (the request was well-formed) returns a Challenge resource. If this data matches a customer registered in the core, the system will connect the user resource to that customer in the banking core and create a new login account.

The client should then use one of the returned challenge's authenticators to verify the user identity. If verified, the user enters their new credentials (username and password) in the client application. The client should then use the createCredentials operation to validate and submit the user's new credentials to create the user's login account.

This operation returns an error respones if the data is not well-formed. Since this operation is unauthenticated, the response for a well-formed request does not indicate success or failure. Thus, this operation cannot be used to confirm if a customer exists or not.

Body parameter

{
  "_profile": "https://api.apiture.com/schemas/users/userConfirmation/v1.0.0/model.json",
  "firstName": "John",
  "lastName": "Smith",
  "birthdate": {},
  "taxId": "112-22-3333"
}

Parameters

Parameter Description
body
(body)
userConfirmation (required)

Try It

Example responses

200 Response

Responses

StatusDescription
200 OK
OK. The response does not indicate if an existing user matching the data exists or not.
Schema: userConfirmationResponse
StatusDescription
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
429 Too Many Requests
Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP will be blocked from further requests until a period of time has passed.
Schema: errorResponse

createCredentials

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/credentials \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'Apiture-Challenge: string' \
  -H 'API-Key: API_KEY'

POST https://api.devbank.apiture.com/auth/credentials HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
Apiture-Challenge: string

var headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'Apiture-Challenge':'string',
  'API-Key':'API_KEY'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/credentials',
  method: 'post',

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

const fetch = require('node-fetch');
const inputBody = '{
  "_profile": "https://api.apiture.com/schemas/auth/credentials/v1.0.0/profie.json",
  "username": "john0224",
  "password": "newPassword",
  "confirmationCode": "12345"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'Apiture-Challenge':'string',
  'API-Key':'API_KEY'

};

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

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => '*/*',
  'Apiture-Challenge' => 'string',
  'API-Key' => 'API_KEY'
}

result = RestClient.post 'https://api.devbank.apiture.com/auth/credentials',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': '*/*',
  'Apiture-Challenge': 'string',
  'API-Key': 'API_KEY'
}

r = requests.post('https://api.devbank.apiture.com/auth/credentials', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/credentials");
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{"*/*"},
        "Apiture-Challenge": []string{"string"},
        "API-Key": []string{"API_KEY"},
        
    }

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

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

Create credentials for a new digital banking platform user

POST /credentials

After confirming the user's identity via the confirmUser operation and completing the identity verification challenge, the user can submit their new username and password with this operation.

If there are no errors in the request, the user login account is completed with the requested username and password; the end user may now log in.

This operation also supports pre-flight validation, via the ?preFlightValidate=true option, to request that the server validate the credentials. The _error object in the 200 OK response will list any such errors, such as username already in use, the password does not conform to the password policies, or the Challenge ID is invalid or expired or has already been redeemed. If the request is valid, there is no _error object in the pre-flight validation response. Validating the request does not count towards the challenge's maximum redemption count.

This operation requires passing a valid Challenge ID in the Apiture-Challenge request header.

Body parameter

{
  "_profile": "https://api.apiture.com/schemas/auth/credentials/v1.0.0/profie.json",
  "username": "john0224",
  "password": "newPassword",
  "confirmationCode": "12345"
}

Parameters

Parameter Description
Apiture-Challenge
(header)
string
The unique identifier of a Challenge resource which demonstrates the user has recently verified their identity. See the discussion of Multi-factor authentication challenges above. The value must be the _id string of a valid, redeemable Challenge resource which matches the challenge context.
preFlightValidate
(query)
boolean
If true, the operation performs pre-flight validation of the request body and it does not attempt to create a login account and credentials for the user.
body
(body)
credentials (required)

Try It

Example responses

200 Response

Responses

StatusDescription
200 OK
OK. The request was accepted and processed. If pre-flight validation was requested, the OK response indicates validation completed, but may have found errors in the request. If ?preFlightValidate=true, the _error will list validation errors, if any.
Schema: credentialsResponse
StatusDescription
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
409 Conflict
Conflict. The username is already in use, or no Apiture-Challenge request header was passed when expected, or the challenge has not been verified, has expired, or has been redeemed too many times, or the account has already been confirmed.
Schema: errorResponse
StatusDescription
422 Unprocessable Entity
Unprecessable Entity. The challenge parameter was malformed or does not refer to an existing or accessible challenge resource.
Schema: errorResponse

Password

passwordResetRequest

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/passwordResetRequests \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

POST https://api.devbank.apiture.com/auth/passwordResetRequests HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: application/json

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'API-Key':'API_KEY'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/passwordResetRequests',
  method: 'post',

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

const fetch = require('node-fetch');
const inputBody = '{
  "username": "john0224",
  "taxId": "1234",
  "birthdate": "1974-10-27"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'API-Key':'API_KEY'

};

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

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'API-Key' => 'API_KEY'
}

result = RestClient.post 'https://api.devbank.apiture.com/auth/passwordResetRequests',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'API-Key': 'API_KEY'
}

r = requests.post('https://api.devbank.apiture.com/auth/passwordResetRequests', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/passwordResetRequests");
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"},
        "API-Key": []string{"API_KEY"},
        
    }

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

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

Initiate a password reset flow.

POST /passwordResetRequests

Initiate a password reset flow by sending the user's key identifying information. A confirmation code is sent to the user via text message or email as a result of this operation if the information matches. In order to complete the flow, a POST request to /passwordResets must contain the confirmation code as well as the username and the desired new password. This operation does not create a new persistent resource; the password reset is transient and returned in the response body only.

Body parameter

{
  "username": "john0224",
  "taxId": "1234",
  "birthdate": "1974-10-27"
}

Parameters

Parameter Description
body
(body)
passwordResetRequest (required)
The data necessary to create a password reset resource.

Try It

Example responses

202 Response

{
  "codeDeliveryMethod": "email",
  "codeDestination": "b***@m***.com"
}

400 Response

Responses

StatusDescription
202 Accepted
Accepted
Schema: passwordReset
StatusDescription
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
429 Too Many Requests
Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP will be blocked from further requests until a period of time has passed.
Schema: errorResponse
StatusDescription
500 Internal Server Error
Server Error. Fatal error has occurred.
Schema: errorResponse

passwordReset

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/passwordResets \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'API-Key: API_KEY'

POST https://api.devbank.apiture.com/auth/passwordResets HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*

var headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'API-Key':'API_KEY'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/passwordResets',
  method: 'post',

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

const fetch = require('node-fetch');
const inputBody = '{
  "_profile": "https://api.apiture.com/schemas/auth/confirmPasswordReset/v1.0.0/profie.json",
  "username": "john0224",
  "newPassword": "newPassword",
  "confirmationCode": "12345"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'API-Key':'API_KEY'

};

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

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => '*/*',
  'API-Key' => 'API_KEY'
}

result = RestClient.post 'https://api.devbank.apiture.com/auth/passwordResets',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': '*/*',
  'API-Key': 'API_KEY'
}

r = requests.post('https://api.devbank.apiture.com/auth/passwordResets', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/passwordResets");
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{"*/*"},
        "API-Key": []string{"API_KEY"},
        
    }

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

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

Complete a password reset flow.

POST /passwordResets

Complete an unauthenticated password reset flow by passing username,confirmationCode, and newPassword in the request. This operation will return 202 Accepted if the request is valid. This operation supports pre-flight validation. If invoked with the preFlightValidate=true query parameter, the operation validates the confirmationCode against the generated code, validates the new password to ensure it complies with the financial institution’s password policy, and returns an _error in the response if there is not a match in the codes or with details of any password policy violations.

Body parameter

{
  "_profile": "https://api.apiture.com/schemas/auth/confirmPasswordReset/v1.0.0/profie.json",
  "username": "john0224",
  "newPassword": "newPassword",
  "confirmationCode": "12345"
}

Parameters

Parameter Description
preFlightValidate
(query)
boolean
If true, the operation performs pre-flight validation of the request body and it does not attempt to update the user's password.
body
(body)
confirmPasswordReset (required)
The data necessary to confirm a password reset

Try It

Example responses

400 Response

Responses

StatusDescription
202 Accepted
Accepted
StatusDescription
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
401 Unauthorized
The client did not include credentials or the credentials are not valid, or the access_token has expired and should be refreshed.
Schema: errorResponse
StatusDescription
422 Unprocessable Entity
Current password does not match or invalid new password.
Schema: errorResponse

changeUserPassword

Code samples

# You can also use wget
curl -X PUT https://api.devbank.apiture.com/auth/my/password \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

PUT https://api.devbank.apiture.com/auth/my/password HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*

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

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/my/password',
  method: 'put',

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

const fetch = require('node-fetch');
const inputBody = '{
  "currentPassword": "currentPassword",
  "newPassword": "newPassword"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/my/password',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

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

result = RestClient.put 'https://api.devbank.apiture.com/auth/my/password',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.put('https://api.devbank.apiture.com/auth/my/password', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/my/password");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
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{"*/*"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://api.devbank.apiture.com/auth/my/password", data)
    req.Header = headers

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

Change the user password

PUT /my/password

An authenticated user must pass currentPassword and newPassword in the request body to change its password. This operation requires both apiKey and accessToken security. This operation will return 202 Accepted if the request is valid. If the request fails, and the user does not know the current password, they can request a password reset by using /passwordResetRequests. This operation supports pre-flight validation. If invoked with the preFlightValidate=true query parameter, the operation only validates the newPassword against the password policies and returns an _error in the response with details of any password policy violations.

Body parameter

{
  "currentPassword": "currentPassword",
  "newPassword": "newPassword"
}

Parameters

Parameter Description
preFlightValidate
(query)
boolean
If true, the operation performs pre-flight validation only of the newPassword and it does not attempt to update the user's password.
body
(body)
passwordChange (required)

Try It

Example responses

200 Response

Responses

StatusDescription
200 OK
OK. It uses for pre-flight validation response. The _error object in the response, if it exists, contains error messages and other detail about the validation (and may contain nested errors).
Schema: passwordChange
202 Accepted
Accepted
StatusDescription
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
401 Unauthorized
The client did not include credentials or the credentials are not valid, or the access_token has expired and should be refreshed.
Schema: errorResponse
StatusDescription
422 Unprocessable Entity
Current password does not match or invalid new password.
Schema: errorResponse

Challenge

redeemChallenge

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/redeemedChallenges?challenge=string \
  -H 'Accept: */*' \
  -H 'If-Match: string' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.devbank.apiture.com/auth/redeemedChallenges?challenge=string HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
If-Match: string

var headers = {
  'Accept':'*/*',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/redeemedChallenges',
  method: 'post',
  data: '?challenge=string',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'*/*',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/redeemedChallenges?challenge=string',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => '*/*',
  'If-Match' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.devbank.apiture.com/auth/redeemedChallenges',
  params: {
  'challenge' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': '*/*',
  'If-Match': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.devbank.apiture.com/auth/redeemedChallenges', params={
  'challenge': 'string'
}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/redeemedChallenges?challenge=string");
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{
        "Accept": []string{"*/*"},
        "If-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

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

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

Redeem or use a challenge

POST /redeemedChallenges

When an operation that requires an identity challenge (passed via the Apiture-Challenge request header), it redeems the challenge to mark it as used. Challenges have a maximum number of times that they may be redeemed. This changes the state property of the authenticator to redeemed. This operation is available via the apiture:redeem link on the challenge resource, if and only if the challenge is eligible for the redeem operation. The response is the updated representation of the challenge.

Parameters

Parameter Description
challenge
(query)
string (required)
A string which uniquely identifies an challenge. This may be the unique _id of the challenge resource or the URI of the challenge.
If-Match
(header)
string
The entity tag that was returned in the ETag response. The If-Match header is optional, but if passed, this must match the current entity tag of the resource.

Try It

Example responses

200 Response

Responses

StatusDescription
200 OK
OK. The operation succeeded. The challenge was updated and its state changed to redeemed and the redeemedAt timestamp updated.
Schema: challenge
StatusDescription
400 Bad Request
Bad Request. The challenge parameter was malformed or does not refer to an existing or accessible challenge resource.
Schema: errorResponse
StatusDescription
409 Conflict
Conflict. The request to redeem the challenged is not allowed. The _error field in the response will contain details about the request error.
StatusDescription
412 Precondition Failed
Precondition Failed. The supplied if-Match header value does not match the most recent ETag response header value. The resource has changed in the interim.
Schema: errorResponse

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for PUT or PATCH operations which update the resource.

getChallenges

Code samples

# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/challenges \
  -H 'Accept: */*' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.devbank.apiture.com/auth/challenges HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*

var headers = {
  'Accept':'*/*',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/challenges',
  method: 'get',

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

const fetch = require('node-fetch');

const headers = {
  'Accept':'*/*',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/challenges',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => '*/*',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.devbank.apiture.com/auth/challenges',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': '*/*',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.devbank.apiture.com/auth/challenges', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/challenges");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
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{
        "Accept": []string{"*/*"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

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

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

Return a collection of challenges

GET /challenges

Return a paginated sortable filterable searchable collection of challenges. The links in the response include pagination links.

Parameters

Parameter Description
start
(query)
integer(int64)
The zero-based index of the first challenge item to include in this page. The default 0 denotes the beginning of the collection.
limit
(query)
integer(int32)
The maximum number of challenge representations to return in this page.
sortBy
(query)
string
Optional sort criteria. See sort criteria format, such as ?sortBy=field1,-field2.
filter
(query)
string
Optional filter criteria. See filtering.
q
(query)
string
Optional search string. See searching.
userId
(query)
string
Subset to challenges for the specified user. The value should be the unique {userId} (the _id of a User resource).
state
(query)
string
Subset the challenges to those whose state matches this value. Use | to separate multiple values. For example, ?state=started matches only items whose state is started; ?state=verified|failed matches items whose state is verified or failed. This is combined with an implicit and with other filters if they are used. See filtering.
Enumerated values:
pending
started
verified
failed
redeemed
expired

Try It

Example responses

200 Response

Responses

StatusDescription
200 OK
OK
Schema: challenges
StatusDescription
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
422 Unprocessable Entity
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The _error field in the response will contain details about the request error.
Schema: errorResponse

createChallenge

Code samples

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

POST https://api.devbank.apiture.com/auth/challenges HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*

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

};

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

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

const fetch = require('node-fetch');
const inputBody = '{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1575c0a7b0115a4b3",
    "message": "Descriptive error message...",
    "statusCode": 422,
    "type": "errorType1",
    "remediation": "Remediation string...",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "errors": [
      {
        "_id": "ccdbe2c5c938a230667b3827",
        "message": "An optional embedded error"
      },
      {
        "_id": "dbe9088dcfe2460f229338a3",
        "message": "Another optional embedded error"
      }
    ],
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/errorType1"
      }
    }
  },
  "reason": "string",
  "contextUri": "string",
  "userId": "string",
  "minimumAuthenticatorCount": 0,
  "maximumRedemptionCount": 1
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/challenges");
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{"*/*"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

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

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

Create a new challenge

POST /challenges

Create a new challenge. This is called from service code when an operations requires additional user verification. By default, the resulting challenge resource will contain a list of authenticators, one for each authenticator type (see the getAuthenticatorTypes operation). When creating a challenge, the service can exclude authenticators with either or both ?exclude= or specify the exact authenticator types to use with ?include=.

When an operation fails with a 401 due to required authentication response, the services embeds the challenge as the _error._embedded.challenge object in the response. See also the getAuthenticator operation and the challenge and authenticator schemas for additional details.

A user may have only one active challenge at a time. Creating a new challenge for a user will delete any outstanding challenge resources for that user and any authenticators associated with those challenges. End users cannot call this operation.

Challenges (and their authenticators) expire automatically some time after creation. At a later time, expired, failed, and verified challenges and authenticators are automatically deleted.

Body parameter

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1575c0a7b0115a4b3",
    "message": "Descriptive error message...",
    "statusCode": 422,
    "type": "errorType1",
    "remediation": "Remediation string...",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "errors": [
      {
        "_id": "ccdbe2c5c938a230667b3827",
        "message": "An optional embedded error"
      },
      {
        "_id": "dbe9088dcfe2460f229338a3",
        "message": "Another optional embedded error"
      }
    ],
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/errorType1"
      }
    }
  },
  "reason": "string",
  "contextUri": "string",
  "userId": "string",
  "minimumAuthenticatorCount": 0,
  "maximumRedemptionCount": 1
}

Parameters

Parameter Description
include
(query)
string
One or more authenticator types or categories which the challenge should exclude from its authenticators. Type names are from the name or category property of the authenticator types resource, such as ?exclude=sms. Multiple types may be specified, separated by commas: ?exclude=sms,biometric. This may be combined with the other filters, but excludes take precedent over ?include. (This notation may be extended in the future to allow additional filter constraints based on authenticator type properties.)
exclude
(query)
string
One or more authenticator types or categories which the challenge should exclude from its authenticators. Type names are from the name or category property of the authenticator types resource, such as ?exclude=sms. Multiple types may be specified, separated by commas: ?exclude=sms,biometric. If both ?include= and ?exclude= are used, the exclusions take precedence inclusions. That is, for ?include=sms&exclude=sms, the sms authenticator will not be used. (This notation may be extended in the future to allow additional filter constraints based on authenticator type properties.)
body
(body)
createChallenge (required)
The data necessary to create a new challenge.

Try It

Example responses

201 Response

Responses

StatusDescription
201 Created
Created
Schema: challenge
StatusDescription
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
429 Too Many Requests
Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP will be blocked from further requests until a period of time has passed.
Schema: errorResponse

Response Headers

StatusDescription
201 Location string uri
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with scheme://host
201 ETag string
An entity tag which may be passed in the If-Match request header for PUT or PATCH operations which update the resource.

getChallenge

Code samples

# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/challenges/{challengeId} \
  -H 'Accept: */*' \
  -H 'If-None-Match: string' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.devbank.apiture.com/auth/challenges/{challengeId} HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
If-None-Match: string

var headers = {
  'Accept':'*/*',
  'If-None-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/challenges/{challengeId}',
  method: 'get',

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

const fetch = require('node-fetch');

const headers = {
  'Accept':'*/*',
  'If-None-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/challenges/{challengeId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => '*/*',
  'If-None-Match' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.devbank.apiture.com/auth/challenges/{challengeId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': '*/*',
  'If-None-Match': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.devbank.apiture.com/auth/challenges/{challengeId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/challenges/{challengeId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
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{
        "Accept": []string{"*/*"},
        "If-None-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

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

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

Fetch a representation of this challenge

GET /challenges/{challengeId}

Return a HAL representation of this challenge resource.

Parameters

Parameter Description
If-None-Match
(header)
string
The entity tag that was returned in the ETag response. If the resource's current entity tag matches, the GET will return 304 (Not Modified) and no response body, else the resource representation will be returned.
challengeId
(path)
string (required)
The unique identifier of this challenge. This is an opaque string.

Try It

Example responses

200 Response

Responses

StatusDescription
200 OK
OK
Schema: challenge
StatusDescription
304 Not Modified
Not Modified. The resource has not been modified since it was last fetched.
StatusDescription
404 Not Found
Not Found. There is no such challenge resource at the specified {challengeId}. The _error field in the response will contain details about the request error.
Schema: errorResponse

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for PUT or PATCH operations which update this challenge resource.

deleteChallenge

Code samples

# You can also use wget
curl -X DELETE https://api.devbank.apiture.com/auth/challenges/{challengeId} \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

DELETE https://api.devbank.apiture.com/auth/challenges/{challengeId} HTTP/1.1
Host: api.devbank.apiture.com

var headers = {
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/challenges/{challengeId}',
  method: 'delete',

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

const fetch = require('node-fetch');

const headers = {
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/challenges/{challengeId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete 'https://api.devbank.apiture.com/auth/challenges/{challengeId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.devbank.apiture.com/auth/challenges/{challengeId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/challenges/{challengeId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
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{
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

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

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

Delete this challenge resource

DELETE /challenges/{challengeId}

Delete this challenge resource and any authenticators that are owned by it. Challenges are also deleted at some interval after they have expired or at an interval after they have been redeemed.

Parameters

Parameter Description
challengeId
(path)
string (required)
The unique identifier of this challenge. This is an opaque string.

Try It

Responses

StatusDescription
204 No Content
No Content. The resource was deleted successfully.

Authenticator

retryAuthenticator

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/retriedAuthenticators?authenticator=string \
  -H 'Accept: */*' \
  -H 'If-Match: string' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.devbank.apiture.com/auth/retriedAuthenticators?authenticator=string HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
If-Match: string

var headers = {
  'Accept':'*/*',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/retriedAuthenticators',
  method: 'post',
  data: '?authenticator=string',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'*/*',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/retriedAuthenticators?authenticator=string',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => '*/*',
  'If-Match' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.devbank.apiture.com/auth/retriedAuthenticators',
  params: {
  'authenticator' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': '*/*',
  'If-Match': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.devbank.apiture.com/auth/retriedAuthenticators', params={
  'authenticator': 'string'
}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/retriedAuthenticators?authenticator=string");
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{
        "Accept": []string{"*/*"},
        "If-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

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

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

Retry an authenticator

POST /retriedAuthenticators

Retry or restart an authenticator, for example, if the authentication process failed or if the user never received confirmation. This changes the state property of the authenticator to started. This fails operation if the authenticator has been retried more than the allowed number of retries.

This operation is available via the apiture:retry link on the authenticator resource, if and only if the authenticator is eligible for the retry operation. The response is the updated representation of the authenticator.

Parameters

Parameter Description
authenticator
(query)
string (required)
A string which uniquely identifies an authenticator. This may be the unique _id of the authenticator or the URI of the authenticator.
If-Match
(header)
string
The entity tag that was returned in the ETag response. The If-Match header is optional, but if passed, this must match the current entity tag of the resource.

Try It

Example responses

200 Response

Responses

StatusDescription
200 OK
OK. The operation succeeded. The authenticator was updated and its state changed to started.
Schema: authenticator
StatusDescription
400 Bad Request
Bad Request. The authenticator parameter was malformed or does not refer to an existing or accessible authenticator.
Schema: errorResponse
StatusDescription
409 Conflict
Conflict. The request to retry the authenticator is not allowed. The _error field in the response will contain details about the request error.
StatusDescription
412 Precondition Failed
Precondition Failed. The supplied if-Match header value does not match the most recent ETag response header value. The resource has changed in the interim.
Schema: errorResponse

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for PUT or PATCH operations which update the resource.

startAuthenticator

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/startedAuthenticators?authenticator=string \
  -H 'Accept: */*' \
  -H 'If-Match: string' \
  -H 'API-Key: API_KEY'

POST https://api.devbank.apiture.com/auth/startedAuthenticators?authenticator=string HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
If-Match: string

var headers = {
  'Accept':'*/*',
  'If-Match':'string',
  'API-Key':'API_KEY'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/startedAuthenticators',
  method: 'post',
  data: '?authenticator=string',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'*/*',
  'If-Match':'string',
  'API-Key':'API_KEY'

};

fetch('https://api.devbank.apiture.com/auth/startedAuthenticators?authenticator=string',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => '*/*',
  'If-Match' => 'string',
  'API-Key' => 'API_KEY'
}

result = RestClient.post 'https://api.devbank.apiture.com/auth/startedAuthenticators',
  params: {
  'authenticator' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': '*/*',
  'If-Match': 'string',
  'API-Key': 'API_KEY'
}

r = requests.post('https://api.devbank.apiture.com/auth/startedAuthenticators', params={
  'authenticator': 'string'
}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/startedAuthenticators?authenticator=string");
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{
        "Accept": []string{"*/*"},
        "If-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        
    }

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

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

Start an authenticator

POST /startedAuthenticators

Start a pending authenticator, initiating the identity verification. For example, starting a sms or email authenticator will send a unique code to the user via that channel. This changes the state property of the authenticator to started and resets the attributes data. A started authenticator should be verified via the verifiedAuthenticator operation. This operation is available via the apiture:start link on the authenticator resource, if and only if the authenticator is eligible for the start operation. The response is the updated representation of the authenticator.

Parameters

Parameter Description
authenticator
(query)
string (required)
A string which uniquely identifies an authenticator. This may be the unique _id of the authenticator or the URI of the authenticator.
If-Match
(header)
string
The entity tag that was returned in the ETag response. The If-Match header is optional, but if passed, this must match the current entity tag of the resource.

Try It

Example responses

200 Response

Responses

StatusDescription
200 OK
OK. The operation succeeded. The authenticator was updated and its state changed to started.
Schema: authenticator
StatusDescription
400 Bad Request
Bad Request. The authenticator parameter was malformed or does not refer to an existing or accessible authenticator, or the request body was not well-formed.
Schema: errorResponse
StatusDescription
409 Conflict
Conflict. The request to start the authenticator is not allowed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
412 Precondition Failed
Precondition Failed. The supplied if-Match header value does not match the most recent ETag response header value. The resource has changed in the interim.
Schema: errorResponse

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for PUT or PATCH operations which update the resource.

verifyAuthenticator

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/verifiedAuthenticators \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'If-Match: string' \
  -H 'API-Key: API_KEY'

POST https://api.devbank.apiture.com/auth/verifiedAuthenticators HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
If-Match: string

var headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'If-Match':'string',
  'API-Key':'API_KEY'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/verifiedAuthenticators',
  method: 'post',

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

const fetch = require('node-fetch');
const inputBody = '{
  "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
  "_profile": "https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json",
  "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
  "state": "started",
  "type": {
    "name": "sms",
    "label": "SMS Code",
    "description": "Enter a code sent via SMS to the user's preferred mobile device.",
    "category": "device",
    "schema": {
      "title": "SMS attributes",
      "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
      "type": "object",
      "required": [
        "code",
        "length"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
          "minLength": 3,
          "maxLength": 10
        },
        "length": {
          "description": "The number of digits/characters that are sent to the user via SMS.",
          "type": "integer",
          "minimum": 3,
          "maximum": 10,
          "example": 6
        }
      }
    }
  },
  "maximumRetries": 3,
  "retryCount": 1,
  "createdAt": "2019-08-23T12:42:50.375Z",
  "expiresAt": "2019-08-23T13:12:50.375Z",
  "_links": {
    "self": {
      "href": "/auth/challenges/2e61e506-1568-4f1a-a93e-4d0a48a06d0e/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
    },
    "apiture:challenge": {
      "href": "/auth/challenges/challenges/b59438cd-5efb-4915-916b-0600bb2a4e1e"
    },
    "apiture:retry": {
      "href": "/auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
    },
    "apiture:verify": {
      "href": "/auth/challenges/verifiedAuthenticators"
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'If-Match':'string',
  'API-Key':'API_KEY'

};

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

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => '*/*',
  'If-Match' => 'string',
  'API-Key' => 'API_KEY'
}

result = RestClient.post 'https://api.devbank.apiture.com/auth/verifiedAuthenticators',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': '*/*',
  'If-Match': 'string',
  'API-Key': 'API_KEY'
}

r = requests.post('https://api.devbank.apiture.com/auth/verifiedAuthenticators', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/verifiedAuthenticators");
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{"*/*"},
        "If-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        
    }

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

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

Verify a user's identity

POST /verifiedAuthenticators

Complete the verification of a user's identity by POSTing the authenticator to this path, passing the authentication data in the authenticator's attributes. For example, to verify an sms or email authenticator, the client should send the code that was sent to the user via SMS or email in attributes.code. If the authentication data is valid, this changes the state property of the authenticator to verified. In addition, if all the challenges' authenticators have been verified successfully, the challenge is also marked as verified. If the attributes data are invalid, the authenticator is marked failed. Failed authenticators may be retried (restarted) via the retryAuthenticator operation. This operation is available via the apiture:verify link on the authenticator resource, if and only if the authenticator is eligible for the apiture:verify operation. The authenticator must have been started (see the startAuthenticator operation and the apiture:start link) before being verified. The response is the updated representation of the authenticator.

Body parameter

{
  "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
  "_profile": "https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json",
  "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
  "state": "started",
  "type": {
    "name": "sms",
    "label": "SMS Code",
    "description": "Enter a code sent via SMS to the user's preferred mobile device.",
    "category": "device",
    "schema": {
      "title": "SMS attributes",
      "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
      "type": "object",
      "required": [
        "code",
        "length"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
          "minLength": 3,
          "maxLength": 10
        },
        "length": {
          "description": "The number of digits/characters that are sent to the user via SMS.",
          "type": "integer",
          "minimum": 3,
          "maximum": 10,
          "example": 6
        }
      }
    }
  },
  "maximumRetries": 3,
  "retryCount": 1,
  "createdAt": "2019-08-23T12:42:50.375Z",
  "expiresAt": "2019-08-23T13:12:50.375Z",
  "_links": {
    "self": {
      "href": "/auth/challenges/2e61e506-1568-4f1a-a93e-4d0a48a06d0e/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
    },
    "apiture:challenge": {
      "href": "/auth/challenges/challenges/b59438cd-5efb-4915-916b-0600bb2a4e1e"
    },
    "apiture:retry": {
      "href": "/auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
    },
    "apiture:verify": {
      "href": "/auth/challenges/verifiedAuthenticators"
    }
  }
}

Parameters

Parameter Description
If-Match
(header)
string
The entity tag that was returned in the ETag response. The If-Match header is optional, but if passed, this must match the current entity tag of the resource.
body
(body)
authenticator (required)
The body is the authenticator object, with the attributes set as per the authenticator type.

Try It

Example responses

200 Response

Responses

StatusDescription
200 OK
OK. The operation succeeded. The authenticator was updated and its state changed to verified.
Schema: authenticator
StatusDescription
400 Bad Request
Bad Request. The authenticator parameter was malformed or does not refer to an existing or accessible authenticator, or the request body was not well-formed.
Schema: errorResponse
StatusDescription
409 Conflict
Conflict. The request to verify the authenticator is not allowed. The _error field in the response will contain details about the request error.
Schema: errorResponse
StatusDescription
412 Precondition Failed
Precondition Failed. The supplied if-Match header value does not match the most recent ETag response header value. The resource has changed in the interim.
Schema: errorResponse

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for PUT or PATCH operations which update the resource.

createAuthenticator

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*

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

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators',
  method: 'post',

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

const fetch = require('node-fetch');
const inputBody = '{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1575c0a7b0115a4b3",
    "message": "Descriptive error message...",
    "statusCode": 422,
    "type": "errorType1",
    "remediation": "Remediation string...",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "errors": [
      {
        "_id": "ccdbe2c5c938a230667b3827",
        "message": "An optional embedded error"
      },
      {
        "_id": "dbe9088dcfe2460f229338a3",
        "message": "Another optional embedded error"
      }
    ],
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/errorType1"
      }
    }
  },
  "type": {
    "name": "sms",
    "label": "SMS code",
    "description": "Enter a code sent via SMS to the user's preferred mobile device.",
    "category": "device",
    "schema": {
      "title": "SMS attributes",
      "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
      "type": "object",
      "required": [
        "code",
        "length"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
          "minLength": 3,
          "maxLength": 10
        },
        "length": {
          "description": "The number of digits/characters that are sent to the user via SMS.",
          "type": "integer",
          "minimum": 3,
          "maximum": 10,
          "example": 6
        }
      }
    }
  },
  "maximumRetries": 0
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

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

require 'rest-client'
require 'json'

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

result = RestClient.post 'https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.post('https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators");
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{"*/*"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

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

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

Create a new authenticator

POST /challenges/{challengeId}/authenticators

Create a new authenticator. This is only called during the creation of a new challenge resource, from the createChallenge operation. End users cannot call this operation.

Body parameter

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1575c0a7b0115a4b3",
    "message": "Descriptive error message...",
    "statusCode": 422,
    "type": "errorType1",
    "remediation": "Remediation string...",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "errors": [
      {
        "_id": "ccdbe2c5c938a230667b3827",
        "message": "An optional embedded error"
      },
      {
        "_id": "dbe9088dcfe2460f229338a3",
        "message": "Another optional embedded error"
      }
    ],
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/errorType1"
      }
    }
  },
  "type": {
    "name": "sms",
    "label": "SMS code",
    "description": "Enter a code sent via SMS to the user's preferred mobile device.",
    "category": "device",
    "schema": {
      "title": "SMS attributes",
      "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
      "type": "object",
      "required": [
        "code",
        "length"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
          "minLength": 3,
          "maxLength": 10
        },
        "length": {
          "description": "The number of digits/characters that are sent to the user via SMS.",
          "type": "integer",
          "minimum": 3,
          "maximum": 10,
          "example": 6
        }
      }
    }
  },
  "maximumRetries": 0
}

Parameters

Parameter Description
body
(body)
createAuthenticator (required)
The data necessary to create a new authenticator.
challengeId
(path)
string (required)
The unique identifier of this challenge. This is an opaque string.

Try It

Example responses

201 Response

Responses

StatusDescription
201 Created
Created
Schema: authenticator
StatusDescription
400 Bad Request
Bad Request. The request body or one or more of the query parameters was not well formed. The _error field in the response will contain details about the request error.
Schema: errorResponse

Response Headers

StatusDescription
201 Location string uri
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with scheme://host
201 ETag string
An entity tag which may be passed in the If-Match request header for PUT or PATCH operations which update the resource.

getAuthenticator

Code samples

# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId} \
  -H 'Accept: */*' \
  -H 'If-None-Match: string' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId} HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
If-None-Match: string

var headers = {
  'Accept':'*/*',
  'If-None-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}',
  method: 'get',

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

const fetch = require('node-fetch');

const headers = {
  'Accept':'*/*',
  'If-None-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => '*/*',
  'If-None-Match' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': '*/*',
  'If-None-Match': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
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{
        "Accept": []string{"*/*"},
        "If-None-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}", data)
    req.Header = headers

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

Fetch a representation of this authenticator

GET /challenges/{challengeId}/authenticators/{authenticatorId}

Return a HAL representation of this authenticator resource. This GET operation is available via the self link of the authenticators inside a challenge resource.

Parameters

Parameter Description
If-None-Match
(header)
string
The entity tag that was returned in the ETag response. If the resource's current entity tag matches, the GET will return 304 (Not Modified) and no response body, else the resource representation will be returned.
challengeId
(path)
string (required)
The unique identifier of this challenge. This is an opaque string.
authenticatorId
(path)
string (required)
The unique identifier of this authenticator. This is an opaque string.

Try It

Example responses

200 Response

Responses

StatusDescription
200 OK
OK
Schema: authenticator
StatusDescription
304 Not Modified
Not Modified. The resource has not been modified since it was last fetched.
StatusDescription
404 Not Found
Not Found. There is no such authenticator resource at the specified {authenticatorId}. The _error field in the response will contain details about the request error.
Schema: errorResponse

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for PUT or PATCH operations which update this authenticator resource.

deleteAuthenticator

Code samples

# You can also use wget
curl -X DELETE https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId} \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

DELETE https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId} HTTP/1.1
Host: api.devbank.apiture.com

var headers = {
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}',
  method: 'delete',

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

const fetch = require('node-fetch');

const headers = {
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete 'https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
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{
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}", data)
    req.Header = headers

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

Delete this authenticator resource

DELETE /challenges/{challengeId}/authenticators/{authenticatorId}

Delete this authenticator resource and any resources that are owned by it. Authenticators are deleted automatically when the challenge is deleted.

Parameters

Parameter Description
challengeId
(path)
string (required)
The unique identifier of this challenge. This is an opaque string.
authenticatorId
(path)
string (required)
The unique identifier of this authenticator. This is an opaque string.

Try It

Responses

StatusDescription
204 No Content
No Content. The resource was deleted successfully.

getAuthenticatorTypes

Code samples

# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/authenticatorTypes \
  -H 'Accept: */*' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.devbank.apiture.com/auth/authenticatorTypes HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*

var headers = {
  'Accept':'*/*',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/authenticatorTypes',
  method: 'get',

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

const fetch = require('node-fetch');

const headers = {
  'Accept':'*/*',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/authenticatorTypes',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => '*/*',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.devbank.apiture.com/auth/authenticatorTypes',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': '*/*',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.devbank.apiture.com/auth/authenticatorTypes', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/authenticatorTypes");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
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{
        "Accept": []string{"*/*"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/authenticatorTypes", data)
    req.Header = headers

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

Retrieve the set of authenticator types

GET /authenticatorTypes

Return the set of reserved authenticator type names. The type property of a authenticator must be one of these values. This set may be updated by the financial institution via the updateAuthenticatorTypes operation. The default list includes the following types:

Try It

Example responses

200 Response

Responses

StatusDescription
200 OK
OK
Schema: authenticatorTypes

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for operations which update the resource.

updateAuthenticatorTypes

Code samples

# You can also use wget
curl -X PUT https://api.devbank.apiture.com/auth/authenticatorTypes \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'If-Match: string' \
  -H 'API-Key: API_KEY' \
  -H 'Authorization: Bearer {access-token}'

PUT https://api.devbank.apiture.com/auth/authenticatorTypes HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
If-Match: string

var headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.devbank.apiture.com/auth/authenticatorTypes',
  method: 'put',

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

const fetch = require('node-fetch');
const inputBody = '{
  "sms": {
    "name": "sms",
    "label": "SMS code",
    "description": "Enter a code sent via SMS to the user's preferred mobile device.",
    "category": "device",
    "schema": {
      "title": "SMS attributes",
      "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
      "type": "object",
      "required": [
        "code",
        "length"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
          "minLength": 3,
          "maxLength": 10
        },
        "length": {
          "description": "The number of digits/characters that are sent to the user via SMS.",
          "type": "integer",
          "minimum": 3,
          "maximum": 10,
          "example": 6
        }
      }
    }
  },
  "email": {
    "name": "email",
    "label": "Email code",
    "description": "Enter a code sent via email to the user's preferred email address.",
    "category": "device",
    "schema": {
      "title": "Email attributes",
      "description": "Schema for an authenticator's `attributes` when the authenticator type is `email`.",
      "type": "object",
      "required": [
        "code",
        "length"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "A code that was sent to the user's preferred email address. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
          "minLength": 3,
          "maxLength": 10
        },
        "length": {
          "description": "The number of digits/characters that are sent to the user via email.",
          "type": "integer",
          "minimum": 3,
          "maximum": 10,
          "example": 6
        }
      }
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'*/*',
  'If-Match':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/authenticatorTypes',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => '*/*',
  'If-Match' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.put 'https://api.devbank.apiture.com/auth/authenticatorTypes',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': '*/*',
  'If-Match': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

r = requests.put('https://api.devbank.apiture.com/auth/authenticatorTypes', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/authenticatorTypes");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
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{"*/*"},
        "If-Match": []string{"string"},
        "API-Key": []string{"API_KEY"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://api.devbank.apiture.com/auth/authenticatorTypes", data)
    req.Header = headers

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

Replace the set of authenticator types

PUT /authenticatorTypes

A financial institution can use this operation to register additional types of authenticators that they may issue to their users when a service needs to issue an identify verification challenge to the user. The type property of an authenticator must be one of these reserved names. This operation completely replaces the set of reserved authenticator type names, so it should include all items from the getAuthenticatorTypes that are in use. This operation is only available to financial institution administrators.

Body parameter

{
  "sms": {
    "name": "sms",
    "label": "SMS code",
    "description": "Enter a code sent via SMS to the user's preferred mobile device.",
    "category": "device",
    "schema": {
      "title": "SMS attributes",
      "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
      "type": "object",
      "required": [
        "code",
        "length"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
          "minLength": 3,
          "maxLength": 10
        },
        "length": {
          "description": "The number of digits/characters that are sent to the user via SMS.",
          "type": "integer",
          "minimum": 3,
          "maximum": 10,
          "example": 6
        }
      }
    }
  },
  "email": {
    "name": "email",
    "label": "Email code",
    "description": "Enter a code sent via email to the user's preferred email address.",
    "category": "device",
    "schema": {
      "title": "Email attributes",
      "description": "Schema for an authenticator's `attributes` when the authenticator type is `email`.",
      "type": "object",
      "required": [
        "code",
        "length"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "A code that was sent to the user's preferred email address. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
          "minLength": 3,
          "maxLength": 10
        },
        "length": {
          "description": "The number of digits/characters that are sent to the user via email.",
          "type": "integer",
          "minimum": 3,
          "maximum": 10,
          "example": 6
        }
      }
    }
  }
}

Parameters

Parameter Description
If-Match
(header)
string
The entity tag that was returned in the ETag response. The If-Match header is optional, but if passed, this must match the current entity tag of the resource.
body
(body)
authenticatorTypes (required)
The set of authenticator types.

Try It

Example responses

200 Response

Responses

StatusDescription
200 OK
OK
Schema: authenticatorTypes
StatusDescription
400 Bad Request
Bad Request. The request body is badly formed or contains invalid data.
Schema: #/components/responses/400
StatusDescription
409 Conflict
Conflict. The request attempts to remove a type that is in use in existing authenticator resources.
Schema: #/components/responses/409AuthenticatorTypesConflict

Response Headers

StatusDescription
200 ETag string
The ETag response header specifies an entity tag which must be provided in an If-Match request header for operations which update the resource.

Schemas

usernameRequest

{
  "lastName": "Smith",
  "taxId": "1234",
  "birthdate": "1975-02-28"
}

Username request (Version v1.0.0)

A request to send a forgotten login username to a user. The user must provide some personal data which helps locate the user.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
lastName string (required)
The user's last name(case sensitive).
taxId string (required)
Last 4 digits of the user tax ID.
minLength: 4
maxLength: 4
birthdate string(date) (required)
The user's birth date in RFC 3339 YYYY-MM-DD date format.

passwordResetRequest

{
  "username": "john0224",
  "taxId": "1234",
  "birthdate": "1974-10-27"
}

Password Reset Request (Version v1.0.0)

Create a new password reset.

Properties

NameDescription
username string (required)
The user's username.
taxId string (required)
Last 4 digits of the user tax ID.
minLength: 4
maxLength: 4
birthdate string(date) (required)
The user's birth date in RFC 3339 YYYY-MM-DD date format.

passwordReset

{
  "codeDeliveryMethod": "email",
  "codeDestination": "b***@m***.com"
}

Password Reset (Version v1.0.0)

Password reset resource.

Properties

NameDescription
codeDeliveryMethod string
Confirmation code delivery method.


Enumerated values:
sms
email

codeDestination string
Masked email address or phone number the confirmation code is sent to.

usernameRequestNotification

{
  "lastName": "Smith",
  "taxId": "1234",
  "birthdate": "1975-02-28"
}

Username Request (Version v1.0.0)

Username request resource.

Properties

NameDescription
lastName string
Last name of user
taxId string
Last 4 digits of the user tax ID.
birthdate string
The user's birth date in RFC 3339 YYYY-MM-DD date format.

authMetadata

{}

Authentication metadata (Version v1.0.0)

A map of (name, value) pairs which describe then the OpenID Provider metadata.

Properties

oauthToken

{
  "access_token": "string",
  "token_type": "string",
  "expires_in": 0,
  "refresh_token": "string"
}

OAuth Tokens (Version v1.0.0)

A response from a credentialed request for tokens.

Properties

NameDescription
access_token string
An opaque string which should be passed (along with the token_type) to subsequent API calls which require authentication. Normally this is done via the the Authorization header of the request: from this response:

Authorization: token_type access_token

token_type string
The form of token returned. This is typically the string Bearer and is the key which subsequent calls should use (along with the access_token above) in the Authorization header when making authenticated API requests.
expires_in integer(int64)
The number of seconds until the access_token expires. When it expires, use the refresh_token to request a new access token.
refresh_token string
A token to use when the access_token expires. The client should retain this securely so it can obtain a new access_token later when the access token expires.

attributes

{
  "property1": {},
  "property2": {}
}

Attributes (Version v2.0.0)

An optional map of name/value pairs which contains additional dynamic data about the resource.

Properties

NameDescription
additionalProperties attributeValue
The data associated with this attribute.

passwordChange

{
  "currentPassword": "currentPassword",
  "newPassword": "newPassword"
}

Password change (Version v1.0.0)

Representation used to change a user password. The request must contain the newPassword and the currentPassword.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
newPassword string(password)
A new user password.
currentPassword string(password)
A current user password. This field is used for performing the change password flow.

confirmPasswordReset

{
  "_profile": "https://api.apiture.com/schemas/auth/confirmPasswordReset/v1.0.0/profie.json",
  "username": "john0224",
  "newPassword": "newPassword",
  "confirmationCode": "12345"
}

Confirm Password Reset (Version v1.0.0)

Representation used to confirm a password reset flow.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
newPassword string(password)
A new user password.
confirmationCode string
A confirmation code send when the user initiated password reset.
username string
The username.

credentials

{
  "_profile": "https://api.apiture.com/schemas/auth/credentials/v1.0.0/profie.json",
  "username": "john0224",
  "password": "newPassword",
  "confirmationCode": "12345"
}

New user credentials (Version v1.0.0)

A new user's requested username and password.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
password string(password)
A new user's password.
username string
The user's requested username.

credentialsResponse

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1575c0a7b0115a4b3",
    "message": "Descriptive error message...",
    "statusCode": 422,
    "type": "errorType1",
    "remediation": "Remediation string...",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "errors": [
      {
        "_id": "ccdbe2c5c938a230667b3827",
        "message": "An optional embedded error"
      },
      {
        "_id": "dbe9088dcfe2460f229338a3",
        "message": "Another optional embedded error"
      }
    ],
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/errorType1"
      }
    }
  }
}

Credentials Response (Version v1.0.0)

Response from submitting new username and password for a new user login account.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.

device

{
  "_profile": "https://api.apiture.com/schemas/auth/device/v1.0.0/profile.json",
  "_id": "us-east-1_b6530c4c-572a-403a-9452-cd0c74c715a1",
  "name": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
  "lastIpAddress": "34.198.94.30",
  "trusted": false,
  "lastLoggedInAt": "2019-06-25T11:48:18.000Z",
  "userId": "testUser"
}

Device (Version v1.0.0)

A device which the user has used to sign in to digital banking.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
_id string
The device unique identifier.
read-only
operatingSystem string
The operating system of the device, if known. iOS, Android, macOS, Windows, Linux are examples. An empty or omitted value indicates the value could not be determined.
read-only
maxLength: 16
vendor string
The vendor of the device, if known. Apple, Google, Samsung, LG are examples. An empty or omitted value indicates the value could not be determined.
read-only
maxLength: 16
secondaryId string
An additional unique host-defined device identifier, for example a unique ID for advertising or other purposes.
name string
The name of the device, derived from the authentication flow.
read-only
type string
The type (category) of the device, if known. 'mobile', 'desktop' are examples. An empty or omitted value indicates the value could not be determined.
read-only
maxLength: 16
lastIpAddress string
The IP address used when the user last logged in with this device.
trusted boolean
If true, the user indicated that the device is trusted when signing in on the device. Future sign ins on the device will not require alternate multi-factor authentication such as entering a code sent by the financial institution via SMS. If false, the user has not indicated the specific device is trusted.
lastLoggedInAt string(date-time)
The timestamp of last login. This is in RFC 3339 format, YYYY-MM-DDThh:mm:ss.sssZ
userId string
The user identified by userId.

devices

{
  "_profile": "https://api.apiture.com/schemas/auth/devices/v1.0.0/profile.json",
  "start": 0,
  "limit": 100,
  "count": 1,
  "name": "devices",
  "_links": {
    "collection": {
      "href": "/auth/users/testUser/devices"
    }
  },
  "_embedded": {
    "items": [
      {
        "_profile": "https://api.apiture.com/schemas/auth/device/v1.0.0/profile.json",
        "_id": "us-east-1_b6530c4c-572a-403a-9452-cd0c74c715a1",
        "name": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
        "lastIpAddress": "34.198.94.30",
        "trusted": false,
        "lastLoggedInAt": "2019-06-25T11:48:18.000Z",
        "userId": "testUser"
      }
    ]
  }
}

Devices (Version v1.0.0)

A collection of devices which user uses to sign in.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
Embedded device objects.
» items [device]
An array of devices which user uses to sign in.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
count integer
The number of items in the collection. This value is optional and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter.
start integer
The start index of this page of items.
limit integer
The maximum number of items per page.
name string
The name of the collection.

createAuthenticator

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1575c0a7b0115a4b3",
    "message": "Descriptive error message...",
    "statusCode": 422,
    "type": "errorType1",
    "remediation": "Remediation string...",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "errors": [
      {
        "_id": "ccdbe2c5c938a230667b3827",
        "message": "An optional embedded error"
      },
      {
        "_id": "dbe9088dcfe2460f229338a3",
        "message": "Another optional embedded error"
      }
    ],
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/errorType1"
      }
    }
  },
  "type": {
    "name": "sms",
    "label": "SMS code",
    "description": "Enter a code sent via SMS to the user's preferred mobile device.",
    "category": "device",
    "schema": {
      "title": "SMS attributes",
      "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
      "type": "object",
      "required": [
        "code",
        "length"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
          "minLength": 3,
          "maxLength": 10
        },
        "length": {
          "description": "The number of digits/characters that are sent to the user via SMS.",
          "type": "integer",
          "minimum": 3,
          "maximum": 10,
          "example": 6
        }
      }
    }
  },
  "maximumRetries": 0
}

Create Authenticator (Version v1.0.0)

A request to create a new authenticator.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
type authenticatorType (required)
The type of this authenticator. This must be one of the items in the /authenticatorTypes resource.
maximumRetries integer
The maximum number of times the user may retry this authenticator. If 0, the user must authenticate correctly on the first try. When an authenticator is retried, the client should POST to the apiture:retry link on the authenticators; absence of the link means the user cannot retry the authenticator. The default is 3.
maximum: 10

authenticator

{
  "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
  "_profile": "https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json",
  "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
  "state": "started",
  "type": {
    "name": "sms",
    "label": "SMS Code",
    "description": "Enter a code sent via SMS to the user's preferred mobile device.",
    "category": "device",
    "schema": {
      "title": "SMS attributes",
      "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
      "type": "object",
      "required": [
        "code",
        "length"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
          "minLength": 3,
          "maxLength": 10
        },
        "length": {
          "description": "The number of digits/characters that are sent to the user via SMS.",
          "type": "integer",
          "minimum": 3,
          "maximum": 10,
          "example": 6
        }
      }
    }
  },
  "maximumRetries": 3,
  "retryCount": 1,
  "createdAt": "2019-08-23T12:42:50.375Z",
  "expiresAt": "2019-08-23T13:12:50.375Z",
  "_links": {
    "self": {
      "href": "/auth/challenges/2e61e506-1568-4f1a-a93e-4d0a48a06d0e/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
    },
    "apiture:challenge": {
      "href": "/auth/challenges/challenges/b59438cd-5efb-4915-916b-0600bb2a4e1e"
    },
    "apiture:retry": {
      "href": "/auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
    },
    "apiture:verify": {
      "href": "/auth/challenges/verifiedAuthenticators"
    }
  }
}

Authenticator (Version v1.0.0)

Representation of authenticators which verify a user's identity.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
type authenticatorType
The type of this authenticator. This must be one of the items in the /authenticatorTypes resource.
maximumRetries integer
The maximum number of times the user may retry this authenticator. If 0, the user must authenticate correctly on the first try. When an authenticator is retried, the client should POST to the apiture:retry link on the authenticators; absence of the link means the user cannot retry the authenticator. The default is 3.
maximum: 10
_id string
The unique identifier for this authenticator resource. This is an immutable opaque string assigned upon creation.
read-only
userId string
The user ID of the user who is requested to verify their identity.
state authenticatorState
The state of this authenticator. This is derived and read-only.
read-only
retryCount integer
The actual number of times a user has retried this authenticator.
read-only
maximum: 10
attributes object
Data collected from the user that is used to verify this authenticator. This data conforms to the schema defined in the type. For example, for sms, the attributes must contains a code.
createdAt string(date-time)
The time stamp when authenticator was created, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ).
read-only
verifiedAt string(date-time)
The time stamp when authenticator was verified in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ).
read-only
failedAt string(date-time)
The time stamp when the user failed to verify their identity verification (authentication) for this challenge, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ).
read-only
expiresAt string(date-time)
The time stamp when the this challenge expires, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ).
read-only

Representations using this authenticator schema may contain the following links:

RelSummaryMethod
apiture:retryRetry an authenticatorPOST
apiture:startStart an authenticatorPOST
apiture:verifyVerify a user's identityPOST
apiture:challengeFetch a representation of this challengeGET

createChallenge

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1575c0a7b0115a4b3",
    "message": "Descriptive error message...",
    "statusCode": 422,
    "type": "errorType1",
    "remediation": "Remediation string...",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "errors": [
      {
        "_id": "ccdbe2c5c938a230667b3827",
        "message": "An optional embedded error"
      },
      {
        "_id": "dbe9088dcfe2460f229338a3",
        "message": "Another optional embedded error"
      }
    ],
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/errorType1"
      }
    }
  },
  "reason": "string",
  "contextUri": "string",
  "userId": "string",
  "minimumAuthenticatorCount": 0,
  "maximumRedemptionCount": 1
}

Create Challenge (Version v1.0.0)

A request to create a user authentication challenge.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
reason string (required)
The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or informational purposes.
contextUri string(url) (required)
The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be for a pending transfer, a user's mailing address, or an account if adding a joint owner.
userId string
The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the challenge.
minimumAuthenticatorCount integer
The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1.
maximum: 4
maximumRedemptionCount integer
The maximum number of times the challenge may be used or redeemed. The default is 1.
minimum: 1

summaryChallenge

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1575c0a7b0115a4b3",
    "message": "Descriptive error message...",
    "statusCode": 422,
    "type": "errorType1",
    "remediation": "Remediation string...",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "errors": [
      {
        "_id": "ccdbe2c5c938a230667b3827",
        "message": "An optional embedded error"
      },
      {
        "_id": "dbe9088dcfe2460f229338a3",
        "message": "Another optional embedded error"
      }
    ],
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/errorType1"
      }
    }
  },
  "reason": "string",
  "contextUri": "string",
  "userId": "string",
  "minimumAuthenticatorCount": 0,
  "maximumRedemptionCount": 1,
  "_id": "string",
  "redemptionCount": 0,
  "state": "pending",
  "createdAt": "2020-03-19T07:32:00Z"
}

Summary Challenge (Version v1.0.0)

Summary representation of a challenge, used in the challenge collection.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
reason string
The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or informational purposes.
contextUri string(url)
The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be for a pending transfer, a user's mailing address, or an account if adding a joint owner.
userId string
The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the challenge.
minimumAuthenticatorCount integer
The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1.
maximum: 4
maximumRedemptionCount integer
The maximum number of times the challenge may be used or redeemed. The default is 1.
minimum: 1
_id string
The unique identifier for this challenge resource. This is an immutable opaque string assigned upon creation.
read-only
redemptionCount integer
How many times the challenge has been redeemed.
read-only
state challengeState
The state of this authenticator.
read-only
createdAt string(date-time)
The time stamp when challenge was created, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ).
read-only

challenge

{
  "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
  "_profile": "https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json",
  "reason": "Transfer amount much higher than normal",
  "contextUri": "https://fi.apiture.com/users/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd/addresses/ha1",
  "minimumAuthenticatorCount": 1,
  "authenticators": [
    {
      "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
      "_profile": "https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json",
      "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
      "state": "started",
      "type": {
        "name": "sms",
        "label": "SMS Code",
        "description": "Enter a code sent via SMS to the user's preferred mobile device.",
        "category": "device",
        "schema": {
          "title": "SMS attributes",
          "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
          "type": "object",
          "required": [
            "code",
            "length"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
              "minLength": 3,
              "maxLength": 10
            },
            "length": {
              "description": "The number of digits/characters that are sent to the user via SMS.",
              "type": "integer",
              "minimum": 3,
              "maximum": 10,
              "example": 6
            }
          }
        }
      },
      "maximumRetries": 3,
      "retryCount": 1,
      "createdAt": "2019-08-23T12:42:50.375Z",
      "expiresAt": "2019-08-23T13:12:50.375Z",
      "_links": {
        "self": {
          "href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
        },
        "apiture:challenge": {
          "href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c"
        },
        "apiture:retry": {
          "href": "/auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
        },
        "apiture:verify": {
          "href": "/auth/challenges/verifiedAuthenticators"
        }
      }
    }
  ],
  "maximumRedemptionCount": 1,
  "redemptionCount": 0,
  "state": "pending",
  "createdAt": "2019-08-23T11:37:55.375Z",
  "expiresAt": "2019-08-23T12:37:55.375Z",
  "_links": {
    "self": {
      "href": "/auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a"
    },
    "apiture:redeem": {
      "href": "/auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a"
    }
  }
}

Challenge (Version v1.0.0)

A resource which represents an identity verification challenge to a user. The user must verify one or more of the authentication methods defined in this challenge in order to proceed with a banking operation (such as scheduling a larger than normal transfer, adding a joint owner or authorized signer to an account, or changing their mailing address or mobile phone number).

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
reason string
The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or informational purposes.
contextUri string(url)
The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be for a pending transfer, a user's mailing address, or an account if adding a joint owner.
userId string
The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the challenge.
minimumAuthenticatorCount integer
The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1.
maximum: 4
maximumRedemptionCount integer
The maximum number of times the challenge may be used or redeemed. The default is 1.
minimum: 1
_id string
The unique identifier for this challenge resource. This is an immutable opaque string assigned upon creation.
read-only
redemptionCount integer
How many times the challenge has been redeemed.
read-only
state challengeState
The state of this authenticator.
read-only
createdAt string(date-time)
The time stamp when challenge was created, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ).
read-only
authenticators [authenticator]
An array of authenticators with which the user can verify their identity. This is derived; the array and the authenticators are constructed in the createChallenge operation.
read-only
redeemable boolean
true if and only if the challenge may be redeemed. This is derived from the states of the challenge's authenticators; if the number of verified authenticators meets or exceeds the minimumAuthenticatorCount, the challenge becomes verified and may be redeemed via a POST to href in the challenge's apiture:redeem link.
read-only
verifiedAt string(date-time)
The time stamp when challenge was verified in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ).
read-only
failedAt string(date-time)
The time stamp when the user failed to verify their identity verification (authentication) for this challenge, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ).
read-only
expiresAt string(date-time)
The time stamp when the this challenge expires, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ).
read-only
redemptionHistory [string]
The time stamps when a service or operation redeemed this challenge, in RFC 3339 UTC date-time format (YYYY-MM-DDThh:mm:ss.sssZ). Item 0 is the time stamp the challenge was first redeemed, item 1 is the time stamp of the next redemption, and so on.
read-only

Representations using this challenge schema may contain the following links:

RelSummaryMethod
apiture:redeemRedeem or use a challengePOST

challengeState

"pending"

Challenge States (Version v1.0.0)

The state of an identity challenge resource. This is derived based on the state of the challenge's authenticators.

NameDescription
Challenge States string
The state of an identity challenge resource. This is derived based on the state of the challenge's authenticators.


Enumerated values:
pending
started
verified
failed
redeemed
expired

Type: string
Enumerated values:
pending
started
verified
failed
redeemed
expired

authenticatorState

"pending"

Authenticator State (Version v1.0.0)

The state of a challenge authenticator resource.

NameDescription
Authenticator State string

The state of a challenge authenticator resource.

  • The startAuthenticator operation (link apiture:start) changes the state from pending to started.
  • The retryAuthenticator operation (link apiture:retry) changes the state to started and is only allowed if the authenticator has more retries available.
  • The verifyAuthenticator operation (link apiture:verify) validates the attributes and changes the state to verified if valid or to failed if invalid.


Enumerated values:
pending
started
verified
failed
expired

Type: string
Enumerated values:
pending
started
verified
failed
expired

challenges

{
  "_profile": "https://api.apiture.com/schemas/challenges/challenges/v1.0.0/profile.json",
  "start": 10,
  "limit": 10,
  "count": 67,
  "name": "challenges",
  "_links": {
    "self": {
      "href": "/auth/challenges?start=10&limit=10"
    },
    "first": {
      "href": "/auth/challenges?start=0&limit=10"
    },
    "next": {
      "href": "/auth/challenges?start=20&limit=10"
    },
    "collection": {
      "href": "/auth/challenges"
    }
  },
  "_embedded": {
    "items": [
      {
        "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
        "_profile": "https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c"
          }
        }
      },
      {
        "_id": "d62c0701-0d74-4836-83f9-ebf3709442ea",
        "_profile": "https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json",
        "_links": {
          "self": {
            "href": "/auth/challenges/d62c0701-0d74-4836-83f9-ebf3709442ea"
          }
        }
      }
    ]
  }
}

Challenge Collection (Version v1.0.0)

Collection of challenges. The items in the collection are ordered in the _embedded.items array; the name is challenges. The top-level _links object may contain pagination links (self, next, prev, first, last, collection.)

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
Embedded objects.
» items [summaryChallenge]
An array containing a page of challenge items.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
count integer
The number of items in the collection. This value is optional and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter.
start integer
The start index of this page of items.
limit integer
The maximum number of items per page.
name string
The name of the collection.

authenticatorCategory

"knowledge"

authenticatorCategory (Version v1.0.0)

Categories which help classify and organize different authenticator types:

NameDescription
authenticatorCategory string

Categories which help classify and organize different authenticator types:

  • knowledge - Something you know, such as a password or answers to personal questions.
  • biometric - Something you are, such as facial recognition or fingerprints.
  • device - Something you have, such as a mobile phone (for confirmation via a code sent via text message) or an electronic key.


Enumerated values:
knowledge
biometric
device

Type: string
Enumerated values:
knowledge
biometric
device

authenticatorTypes

{
  "sms": {
    "name": "sms",
    "label": "SMS code",
    "description": "Enter a code sent via SMS to the user's preferred mobile device.",
    "category": "device",
    "schema": {
      "title": "SMS attributes",
      "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
      "type": "object",
      "required": [
        "code",
        "length"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
          "minLength": 3,
          "maxLength": 10
        },
        "length": {
          "description": "The number of digits/characters that are sent to the user via SMS.",
          "type": "integer",
          "minimum": 3,
          "maximum": 10,
          "example": 6
        }
      }
    }
  },
  "email": {
    "name": "email",
    "label": "Email code",
    "description": "Enter a code sent via email to the user's preferred email address.",
    "category": "device",
    "schema": {
      "title": "Email attributes",
      "description": "Schema for an authenticator's `attributes` when the authenticator type is `email`.",
      "type": "object",
      "required": [
        "code",
        "length"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "A code that was sent to the user's preferred email address. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
          "minLength": 3,
          "maxLength": 10
        },
        "length": {
          "description": "The number of digits/characters that are sent to the user via email.",
          "type": "integer",
          "minimum": 3,
          "maximum": 10,
          "example": 6
        }
      }
    }
  }
}

Authenticator types (Version v1.0.0)

A set of methods by which a user can authenticate in order to verify their identity. The type property of an authentication must match one of the keys in this object. The keys in this object are names of the authenticators.

Properties

NameDescription
additionalProperties authenticatorType
An authenticator type description.

authenticatorType

{
  "name": "sms",
  "label": "SMS code",
  "description": "Enter a code sent via SMS to the user's preferred mobile device.",
  "category": "device",
  "schema": {
    "title": "SMS attributes",
    "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
    "type": "object",
    "required": [
      "code",
      "length"
    ],
    "properties": {
      "code": {
        "type": "string",
        "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
        "minLength": 3,
        "maxLength": 10
      },
      "length": {
        "description": "The number of digits/characters that are sent to the user via SMS.",
        "type": "integer",
        "minimum": 3,
        "maximum": 10,
        "example": 6
      }
    }
  }
}

Authenticator Type (Version v1.0.0)

An authenticator type description.

Properties

NameDescription
name string
The name of this authenticator; also the key in the authenticatorTypes object.
label string
A localized label or title which may be used labels or other UI controls which present a value.
description string
A more detailed localized description of an authenticator type.
language string
The actual natural language tag to which this authentication type description is associated, as per RFC 7231. If omitted, this serves as the default.
category authenticatorCategory
The authentication category.
schema object
The JSON schema which describe the attributes object for all authenticators of this type. For example, for sms, the schema defines a required code string.

challengeErrorResponse

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "message": "string",
    "_id": "string",
    "statusCode": 422,
    "type": "string",
    "occurredAt": "2018-02-02T03:37:15.375Z",
    "attributes": {
      "property1": {},
      "property2": {}
    },
    "remediation": "string",
    "errors": [
      {
        "_id": "2eae46e1575c0a7b0115a4b3",
        "message": "Descriptive error message...",
        "statusCode": 422,
        "type": "errorType1",
        "remediation": "Remediation string...",
        "occurredAt": "2018-01-25T05:50:52.375Z",
        "errors": [
          {
            "_id": "ccdbe2c5c938a230667b3827",
            "message": "An optional embedded error"
          },
          {
            "_id": "dbe9088dcfe2460f229338a3",
            "message": "Another optional embedded error"
          }
        ],
        "_links": {
          "describedby": {
            "href": "https://developer.apiture.com/errors/errorType1"
          }
        }
      }
    ],
    "_links": {
      "property1": {
        "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
        "title": "Applicant"
      },
      "property2": {
        "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
        "title": "Applicant"
      }
    },
    "_embedded": {
      "challenge": {
        "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
        "_profile": "https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json",
        "reason": "Transfer amount much higher than normal",
        "contextUri": "https://fi.apiture.com/users/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd/addresses/ha1",
        "minimumAuthenticatorCount": 1,
        "authenticators": [
          {
            "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
            "_profile": "https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json",
            "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
            "state": "started",
            "type": {
              "name": "sms",
              "label": "SMS Code",
              "description": "Enter a code sent via SMS to the user's preferred mobile device.",
              "category": "device",
              "schema": {
                "title": "SMS attributes",
                "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
                "type": "object",
                "required": [
                  "code",
                  "length"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
                    "minLength": 3,
                    "maxLength": 10
                  },
                  "length": {
                    "description": "The number of digits/characters that are sent to the user via SMS.",
                    "type": "integer",
                    "minimum": 3,
                    "maximum": 10,
                    "example": 6
                  }
                }
              }
            },
            "maximumRetries": 3,
            "retryCount": 1,
            "createdAt": "2019-08-23T12:42:50.375Z",
            "expiresAt": "2019-08-23T13:12:50.375Z",
            "_links": {
              "self": {
                "href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
              },
              "apiture:challenge": {
                "href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c"
              },
              "apiture:retry": {
                "href": "/auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
              },
              "apiture:verify": {
                "href": "/auth/challenges/verifiedAuthenticators"
              }
            }
          }
        ],
        "maximumRedemptionCount": 1,
        "redemptionCount": 0,
        "state": "pending",
        "createdAt": "2019-08-23T11:37:55.375Z",
        "expiresAt": "2019-08-23T12:37:55.375Z",
        "_links": {
          "self": {
            "href": "/auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a"
          },
          "apiture:redeem": {
            "href": "/auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a"
          }
        }
      }
    }
  }
}

Challenge Error Response (Version v1.0.0)

When an operation requires an additional identity verification challenge, it returns a 401 Unauthorized response status code and an error response with a challenge resource embedded in the _error._embedded.challenge. This informs the caller that they should verify the challenge via one or more of its authenticators, then retry the operation with the Apiture-Challenge header that references the challenge's _id.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error challengeError
The description of the error.

challengeError

{
  "message": "string",
  "_id": "string",
  "statusCode": 422,
  "type": "string",
  "occurredAt": "2018-02-02T03:37:15.375Z",
  "attributes": {
    "property1": {},
    "property2": {}
  },
  "remediation": "string",
  "errors": [
    {
      "_id": "2eae46e1575c0a7b0115a4b3",
      "message": "Descriptive error message...",
      "statusCode": 422,
      "type": "errorType1",
      "remediation": "Remediation string...",
      "occurredAt": "2018-01-25T05:50:52.375Z",
      "errors": [
        {
          "_id": "ccdbe2c5c938a230667b3827",
          "message": "An optional embedded error"
        },
        {
          "_id": "dbe9088dcfe2460f229338a3",
          "message": "Another optional embedded error"
        }
      ],
      "_links": {
        "describedby": {
          "href": "https://developer.apiture.com/errors/errorType1"
        }
      }
    }
  ],
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {
    "challenge": {
      "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
      "_profile": "https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json",
      "reason": "Transfer amount much higher than normal",
      "contextUri": "https://fi.apiture.com/users/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd/addresses/ha1",
      "minimumAuthenticatorCount": 1,
      "authenticators": [
        {
          "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
          "_profile": "https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json",
          "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
          "state": "started",
          "type": {
            "name": "sms",
            "label": "SMS Code",
            "description": "Enter a code sent via SMS to the user's preferred mobile device.",
            "category": "device",
            "schema": {
              "title": "SMS attributes",
              "description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
              "type": "object",
              "required": [
                "code",
                "length"
              ],
              "properties": {
                "code": {
                  "type": "string",
                  "description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
                  "minLength": 3,
                  "maxLength": 10
                },
                "length": {
                  "description": "The number of digits/characters that are sent to the user via SMS.",
                  "type": "integer",
                  "minimum": 3,
                  "maximum": 10,
                  "example": 6
                }
              }
            }
          },
          "maximumRetries": 3,
          "retryCount": 1,
          "createdAt": "2019-08-23T12:42:50.375Z",
          "expiresAt": "2019-08-23T13:12:50.375Z",
          "_links": {
            "self": {
              "href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
            },
            "apiture:challenge": {
              "href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c"
            },
            "apiture:retry": {
              "href": "/auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
            },
            "apiture:verify": {
              "href": "/auth/challenges/verifiedAuthenticators"
            }
          }
        }
      ],
      "maximumRedemptionCount": 1,
      "redemptionCount": 0,
      "state": "pending",
      "createdAt": "2019-08-23T11:37:55.375Z",
      "expiresAt": "2019-08-23T12:37:55.375Z",
      "_links": {
        "self": {
          "href": "/auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a"
        },
        "apiture:redeem": {
          "href": "/auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a"
        }
      }
    }
  }
}

Challenge Error (Version v1.0.0)

The operation error description with an embedded identity challenge.

Properties

NameDescription
message string
A localized message string describing the error condition.
_id string
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string.
read-only
statusCode integer
The HTTP status code associate with this error.
minimum: 100
maximum: 599
type string
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode. For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet.
occurredAt string(date-time)
An RFC 3339 UTC time stamp indicating when the error occurred.
attributes attributes
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type.
remediation string
An optional localized string which provides hints for how the user or client can resolve the error.
errors [error]
An optional array of nested error objects. This property is not always present.
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
Embedded objects
» challenge challenge
The details of the identity verification challenge.

userConfirmation

{
  "_profile": "https://api.apiture.com/schemas/users/userConfirmation/v1.0.0/model.json",
  "firstName": "John",
  "lastName": "Smith",
  "birthdate": {},
  "taxId": "112-22-3333"
}

User Confirmation Request (Version v1.0.0)

User data which confirms a customer has a banking account at the financial institution. The service does not persist this data.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
firstName string (required)
The person's first name (or given name).
lastName string (required)
The person's last name (or surname).
birthdate string(date) (required)
The contact's birth date in YYYY-MM-DD format.
taxId string (required)
Official government identification (tax ID) for this person.
maxLength: 16

userConfirmationResponse

{
  "_profile": "https://api.apiture.com/schemas/users/userConfirmationResponse/v1.0.0/model.json"
}

User Confirmation Response (Version v1.0.0)

Response from confirming a user within the platform. If the request was well-formed, the response contain a Challenge resource with one or more authenticators. The client should start one of the challenge's authenticators, and after verifying the chosen authenticator, the client should pass the value of the challenge's _id as the Apiture-Challenge header on the createCredentials operation which requires an identity challenge/verification. This response does not confirm or deny that the customer exists.

If the request was ill-formed, the _error describes the problem.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
challenge challenge
A Challenge resource.

Representations using this userConfirmationResponse schema may contain the following links:

RelSummaryMethod
apiture:createCredentialsCreate credentials for a new digital banking platform userPOST

userSessionStart

{
  "_profile": "https://api.apiture.com/auth/userSessionStart/v1.0.0/model.json",
  "mfa": {
    "performed": true,
    "tryCount": 1
  }
}

User Session Start (Version v1.0.0)

Client information for starting the new user session. The request should inlude the mobileDevice object if the client is a mobile device.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
mobileDevice mobileDevice
Information about the mobile device, if the user session is from a native mobile application.
mfa startSessionMfa
Information related to the multi-factor authentication used to validate the user's login.

startSessionMfa

{
  "performed": true,
  "tryCount": 1
}

Start Session MFA (Version v1.0.0)

Information related to the multi-factor authentication used to verify the user's log in.

Properties

NameDescription
performed boolean (required)
If true, the client participated in and completed the MFA flow. If false, the log in either did not require MFA, or it performed the MFA flow such that the client was unaware of it.
tryCount integer
The number of times the user tried to authenticate with MFA for this session. This value only applies if performed is true.

mobileDevice

{
  "_id": "string",
  "operatingSystem": "string",
  "vendor": "string",
  "secondaryId": "string",
  "gpsCoordinates": {
    "latitude": -77.9041,
    "longitude": 34.2006
  },
  "compromised": true,
  "clientApplicationVersion": "string",
  "operatingSystemVersion": "string"
}

Mobile Device (Version v1.0.0)

Information about the mobile device, if the user session is from a native mobile application.

Properties

NameDescription
_id string
The device unique identifier.
read-only
operatingSystem string
The operating system of the device, if known. iOS, Android, macOS, Windows, Linux are examples. An empty or omitted value indicates the value could not be determined.
read-only
maxLength: 16
vendor string
The vendor of the device, if known. Apple, Google, Samsung, LG are examples. An empty or omitted value indicates the value could not be determined.
read-only
maxLength: 16
secondaryId string
An additional unique host-defined device identifier, for example a unique ID for advertising or other purposes.
gpsCoordinates gpsCoordinates
The GPS coordinates at the time the request is made. This may be blank if the user has not granted the application access to the device GPS or the device does not have GPS. The format is "lat,long" where each of latitude and longitude
compromised boolean
Indicates if device analysis shows the device may be compromised, such as rooted or jailbroken.
clientApplicationVersion string
The version of the client application.
operatingSystemVersion string
The version of the device's native operating system

gpsCoordinates

{
  "latitude": -77.9041,
  "longitude": 34.2006
}

GPS Coordinates (Version v1.0.0)

Map coordinates (latitues, longitude) of a geographical point.

Properties

NameDescription
latitude number (required)
Latitude of a geographical point on the map. Represented in decimal notation.
minimum: -90
maximum: 90
longitude number (required)
Longitude of a geographical point on the map. Represented in decimal notation.
minimum: -180
maximum: 180

userSession

{
  "_profile": "https://api.apiture.com/auth/userSession/v1.0.0/model.json",
  "_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}

User Session (Version v1.0.0)

A user session. This representation contains links to continued the user session (POST) or end this user session (POST); the request and response body for both is a `userSession' object.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
_id string
The user session identifier.

Representations using this userSession schema may contain the following links:

RelSummaryMethod
apiture:continueUserSessionPOST
apiture:endUserSessionPOST

root

{
  "id": "apiName",
  "name": "API name",
  "apiVersion": "1.0.0",
  "_profile": "https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json",
  "_links": {}
}

API Root (Version v2.0.0)

A HAL response, with hypermedia _links for the top-level resources and operations in API.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
_id string
This API's unique ID.
read-only
name string
This API's name.
apiVersion string
This API's version.

errorResponse

{
  "_profile": "https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json",
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "The value for deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": -125.5
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://api.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  }
}

Error Response (Version v2.0.0)

Describes an error response, typically returned on 4xx or 5xx errors from API operations. The _error object contains the error details.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.

abstractRequest

{
  "_profile": "{uri of resource profile.json}",
  "_links": {
    "self": {
      "href": "{uri of current resource}"
    }
  }
}

Abstract Request (Version v2.0.0)

An abstract schema used to define other request-only schemas. This is a HAL resource representation, minus the _error defined in abstractResource.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.

abstractResource

{
  "_profile": "{uri of resource profile.json}",
  "_links": {
    "self": {
      "href": "{uri of current resource}"
    }
  }
}

Abstract Resource (Version v2.0.0)

An abstract schema used to define other schemas for request and response bodies. This is a HAL resource representation. This model contains hypermedia _links, and either optional domain object data with _profile and optional _embedded objects, or an _error object. In responses, if the operation was successful, this object will not include the _error, but if the operation was a 4xx or 5xx error, this object will not include _embedded or any data fields, only _error and optionally _links.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.

collection

{
  "_links": {
    "property1": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    },
    "property2": {
      "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
      "title": "Applicant"
    }
  },
  "_embedded": {},
  "_profile": "http://example.com",
  "_error": {
    "_id": "2eae46e1575c0a7b0115a4b3",
    "message": "Descriptive error message...",
    "statusCode": 422,
    "type": "errorType1",
    "remediation": "Remediation string...",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "errors": [
      {
        "_id": "ccdbe2c5c938a230667b3827",
        "message": "An optional embedded error"
      },
      {
        "_id": "dbe9088dcfe2460f229338a3",
        "message": "Another optional embedded error"
      }
    ],
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/errorType1"
      }
    }
  },
  "count": 0,
  "start": 0,
  "limit": 0,
  "name": "string"
}

Collection (Version v2.0.0)

A collection of resources. This is an abstract model schema which is extended to define specific resource collections.

Properties

NameDescription
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
_embedded object
An optional map of nested resources, mapping each nested resource name to a nested resource representation.
_profile string(uri)
The URI of a resource profile which describes the representation.
_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
count integer
The number of items in the collection. This value is optional and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter.
start integer
The start index of this page of items.
limit integer
The maximum number of items per page.
name string
The name of the collection.

error

{
  "_id": "2eae46e1575c0a7b0115a4b3",
  "message": "Descriptive error message...",
  "statusCode": 422,
  "type": "errorType1",
  "remediation": "Remediation string...",
  "occurredAt": "2018-01-25T05:50:52.375Z",
  "errors": [
    {
      "_id": "ccdbe2c5c938a230667b3827",
      "message": "An optional embedded error"
    },
    {
      "_id": "dbe9088dcfe2460f229338a3",
      "message": "Another optional embedded error"
    }
  ],
  "_links": {
    "describedby": {
      "href": "https://developer.apiture.com/errors/errorType1"
    }
  }
}

Error (Version v2.0.0)

Describes an error in an API request or in a service called via the API.

Properties

NameDescription
message string (required)
A localized message string describing the error condition.
_id string
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string.
read-only
statusCode integer
The HTTP status code associate with this error.
minimum: 100
maximum: 599
type string
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode. For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet.
occurredAt string(date-time)
An RFC 3339 UTC time stamp indicating when the error occurred.
attributes attributes
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type.
remediation string
An optional localized string which provides hints for how the user or client can resolve the error.
errors [error]
An optional array of nested error objects. This property is not always present.
_links links
An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.

{
  "property1": {
    "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
    "title": "Applicant"
  },
  "property2": {
    "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
    "title": "Applicant"
  }
}

Links (Version v1.0.0)

An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.

Properties

NameDescription
additionalProperties link
Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.

{
  "href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
  "title": "Applicant"
}

Link (Version v1.0.0)

Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property.

Properties

NameDescription
href string(uri) (required)
The URI or URI template for the resource/operation this link refers to.
type string
The media type for the resource.
templated boolean
If true, the link's href is a URI template.
title string
An optional human-readable localized title for the link.
deprecation string(uri)
If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.
profile string(uri)
The URI of a profile document, a JSON document which describes the target resource/operation.

attributeValue

{}

Attribute Value (Version v2.0.0)

The data associated with this attribute.

Properties