Auth v0.33.0

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

The 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.

Creating a client

Request an OAuth client key and secret by visiting developer.apiture.com, registering your partner organization, defining a new client application, and requesting API keys for that application and a target environment.

After submitting the request, Apiture provisions the API keys and the client ID and client secret which allow the client's user to authenticate and request authentication tokens at run time; these authentication tokens and the API key are used to authenticate each API request. See Secure Access for further details.

Open ID Connect and OAuth 2.0 Authentication

The Authentication API supports OpenID Connect (OIDC) authentication flows and OAuth 2.0:

Authorization Code Flow (OpenID Connect), for Mobile Applications or Web Applications or apps where a user logs in
Client Credentials Grant (OAuth 2.0), for back-end service applications in a secure environment

More information about OIDC discovery and using these flows are in the Secure Coding document in the Dev Portal.

OpenID Connect Discovery

When your application starts, it should call the getApi operation. The response includes the OpenID Connect Discovery configuration URL in the apiture:openidConfiguration link. Tip: Do not hard-code the URL into your client application; it may vary over time or between applications.

OpenID Connect Authorization Code Flow

This interactive flow involves browser redirection to the Apiture Identity Provider URL (the OAuth authorization server and OIDC authorization_endpoint) for secure user login and consent. After authenticating, the user is redirected back to the requesting application using the callback URL registered with the client application in the Dev Portal. Register applications in the Dev Portal using the Authorization Code authentication type to use this flow for web and mobile applications. See Secure Access for further details.

OAuth 2.0 Client Credentials Grant

With this authentication method, the client requests an authentication token, passing the client ID and client secret that have been provisioned by the developer portal for applications registered with the Client Credentials authentication type. This method does not use user authentication or credentials; hence the access token is not associated with a financial institution customer. This is only suitable for secure applications, such as those in a financial institution's data center. Web or mobile applications must not use this authentication method. See Secure Access for further details.

Using the Access Tokens

Each request to a secured endpoint must include the access token as part of the Authorization header: Authorization: {token_type} {access_token}. The {token_type} is typically Bearer. Apiture API operations which have a security requirement of accessToken must use this Authorization header.

The access token has an expiration time in milliseconds in the expires_in property in the response, and the the refresh token (for Authorization Code Flow) is in the refresh_token property. To refresh an expiring or expired access token, use the token_endpoint from OIDC Discovery with the grant_type form parameter set to refresh_token, and the refresh_token form parameter set to the refresh_token obtained when the token was last issued.

Forgotten password reset flow

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

Start the process by issuing a POST to /passwordResetRequests with the user's username, taxId, and birthdate. A confirmation code is sent via the pre-configured delivery channel as a result of this operation.
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 is acknowledged with a 202 status code.

Changing the user password

To change a user's password, an already authenticated user should POST to /my/password. The client should encrypt the old and new password using client side encryption keys obtained from the GET /encryptionKeys. See Encryption for additional details.

An operator can initiate the password reset process for a user via sendPasswordResetInstructions.

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 text message (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 remembers 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 primary account owner and joint account owner logging onto digital banking on a shared laptop or table. If the primary owner has chosen to trust the device, they may sign in using the device and not have to use secondary authentication such as an code sent via SMS. If the joint owner has not marked the device as trusted, when they sign in, they 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 Authenticators 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 without the owner's consent or knowledge and attempts to take it over 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:

a contextUri - the URI of a resource which the challenge is requested (such as the Transfers API, or the Accounts API), a set of authentication types)
an array of authenticators which the end user can select from in order to verify their identity
a reason that the service is requesting additional authentication
the userId of the user who is being challenged
createdAt, verifiedAt, and failedAt, and redeemedAt timestamps.
the state of the challenge
other data for limiting and tracking redemption (use) of a challenge

An authenticator contains

the authentication type such as sms or email
the authentication category such as knowledge, biometric, device
additional authentication details in attributes
a link to a JSON schema that describes the attributes
a link to the challenge to which it relates
createdAt, verifiedAt, and failedAt timestamps
maximumRetries limits how many times an authenticator may be retried

For example, a type may be sms which means the authenticator sends an SMS message to the user's mobile device; the message contains a code (typically 4 to 8 digits) which the user must enter in the application. The schema attached to sms lists 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 sends 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 documents 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.

Error Types

Error responses in this API may have one of the type values described below. See Errors for more information on error responses and error types.

accessDenied

Description: The credentials supplied in the request are insufficient to grant access.
Remediation: Check the supplied credentials for validity.

accountAlreadyConfirmed

Description: A user has already confirmed this login account.
Remediation: Your login account is ready for use. You can login or use the Forgot Password option if you have forgotten your username.

authenticatorAttemptsExceeded

Description: User has exceeded the allowed number of retry attempts.
Remediation: Consider locking this user or device in order to prevent fraud.

The attributes object in the error may have the following properties:

Property	Type	Description
authenticatorId	`string`	undefined
maximumRetries	`number`	undefined
retryCount	`number`	undefined

authenticatorNotCompletable

Description: The authenticator is not in a state that allows completing.
Remediation: Only verify an authenticator if the apiture:verify link exists.

authenticatorNotFound

Description: No authenticators were found for the specified authenticatorId and challengeId combination.
Remediation: Ensure the supplied authenticatorId corresponds to a valid authenticator resource.

authenticatorRefNotFound

Description: There is no authenticator resource corresponding to the referenced authenticator.
Remediation: Pass a reference to a valid authenticator resource.

authenticatorTypeInUse

Description: An update to the authenticator types omits one or more types that are in use.
Remediation: Include all in-use type names.

The attributes object in the error may have the following properties:

Property	Type	Description
typeNames	[`undefined`]	The list of authenticator types that are in use but missing from the request. Example: `sms,email`

captchaAlreadySubmitted

Description: The CAPTCHA has already been submitted.
Remediation: Restart the request and collect a new CAPTCHA value for each request.

captchaThresholdNotMet

Description: The CAPTCHA was valid but the score did not meet the required threshold.
Remediation: Retry the CAPTCHA with a fallback method.

challengeNotFound

Description: No Challenge was found for the specified challengeId.
Remediation: Ensure the supplied challengeId corresponds to a valid challenge resource.

challengeRefNotFound

Description: There is no challenge resource corresponding to the referenced challenge.
Remediation: Pass a reference to a valid challenge resource.

challengedAlreadyRedeemed

Description: The challenge resource has already been redeemed.
Remediation: Use the most recently issued challenge.

challengedExpired

Description: The challenge resource has expired.
Remediation: Use the most recently issued challenge and complete the authenticators before the challenge expires.

challengedNotVerified

Description: The challenge has not been verified, has expired, or has been redeemed too many times.
Remediation: Pass a valid and verified challenge resource in the Apiture-Challenge request header.

createTokenAccessDenied

Description: The client is not authorized to generate this token.
Remediation: Make sure the client credentials are valid.

currentPasswordDoesNotMatch

Description: The current password does not match.
Remediation: Check that the current password in the request match the user's current password.

dataNotEncrypted

Description: The data in request was not encrypted or it was encrypted with obsolete keys.
Remediation: Encrypt the data using valid encryption keys.

duplicateUsername

Description: A user with the given username already exists.
Remediation: Resubmit the operation with a unique username.

emailNotFound

Description: The email address in the request does not match an approved email address for the user.
Remediation: Pass an approved email address (normally the email address named by the preferredEmailAddressId of the user).

expiredCaptcha

Description: The CAPTCHA has expired.
Remediation: Collect a new CAPTCHA value an retry the request with the new CAPTCHA response.

invalidAuthenticatorAttributes

Description: The attributes in the authenticator do not conform to the schema for the authenticator type.
Remediation: Pass attributes that satisfy the JSON schema for the authenticator's type.

invalidAuthenticatorState

Description: The operation is not allowed from the authenticator’s current state.
Remediation: Ensure the supplied authenticatorId corresponds to an Apiture authenticator resource in the correct state.

The attributes object in the error may have the following properties:

Property	Type	Description
currentState	`string`	undefined
allowedStates	[`undefined`]	undefined

invalidCaptcha

Description: The CAPTCHA is invalid.
Remediation: Start the CAPTCHA correctly in the client and send the correct ID after the CAPTCHA completes.

invalidNewPassword

Description: The new password is not valid.
Remediation: Check that the new password conforms to password policy.

invalidNewUsername

Description: The new username is not valid.
Remediation: Check that the new username conforms to username policy.

invalidSession

Description: No session was found.
Remediation: Resubmit request with a valid session.

invalidSymbolForNonEmailUsernameFormat

Description: Username cannot contain the ‘@’ symbol.
Remediation: Choose a new username without the ‘@’ symbol.

invalidUser

Description: The userUri does not match a valid user resource.
Remediation: Pass the URI of a valid, verified user.

invalidUsername

Description: For your security, we recommend choosing a more complex username with at least one special character.
Remediation: Choose a new username that satisfies the financial institution's policies or is more complex, such as including special characters.

The attributes object in the error may have the following properties:

Property	Type	Description
specialCharacters	`string`	A string containing recommended special characters.

invalidUsernameRequest

Description: The username request was not processed.
Remediation: Check that the user exists and that the attributes match the request.

missingApitureChallengeHeader

Description: The Apiture-Challenge request header is missing.
Remediation: Pass a reference to a valid challenge resource in the Apiture-Challenge header.

noSuchDevice

Description: No devices were found for the specified userId.
Remediation: Verify that the device exists for the user and resubmit.

noSuchUser

Description: No users were found for the specified userId.
Remediation: Ensure the supplied userId corresponds to an Apiture user.

redeemChallengeConflict

Description: 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.
Remediation: Ensure the supplied challengeId corresponds to a valid challenge resource.

Download OpenAPI Definition (YAML)

Base URLs:

https://api.devbank.apiture.com/auth

Email: Apiture Web: Apiture

Authentication

API Key (apiKey)
- header parameter: API-Key
- API Key based authentication. Each client application must pass its private, unique API key, allocated in the developer portal, via the API-Key: {api-key} request header.

OAuth2 authentication (accessToken)
- OAuth2 client access token authentication. The client authenticates against the server at authorizationUrl, passing the client's private clientId (and optional clientSecret) as part of this flow. The client obtains an access token from the server at tokenUrl. It then passes the received access token via the Authorization: Bearer {access-token} header in subsequent API calls. The authorization process also returns a refresh token which the client should use to renew the access token before it expires.
- Flow: authorizationCode
- Authorization URL = https://auth.devbank.apiture.com/auth/oauth2/authorize
- Token URL = https://api.devbank.apiture.com/auth/oauth2/token

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

OpenID Connect

OpenID Connect Discovery and Authorization using OAuth 2.0

authorize

Code samples

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

GET https://api.devbank.apiture.com/auth/oauth2/authorize?client_id=string&redirect_uri=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&redirect_uri=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&redirect_uri=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',
'redirect_uri' => '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',  'redirect_uri': 'string'
}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/oauth2/authorize?client_id=string&redirect_uri=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 the authorization server for secure user login~~

~~GET /oauth2/authorize~~

deprecated
Start OpenID Connect Authorization Code Flow by requesting client application authorization and user authentication. This request redirects the user to the identity provider login page to authenticate by securely entering their credentials. Upon a successful 302 response, the client should validate the Location URI then redirect to that URI.
Warning: The operation authorize was deprecated on version v0.29.1 of the API. Use the authorization_endpoint in the OpenID Connect configuration instead. authorize will be removed on version v0.35.0 of the API.

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 `client_credentials` for the OAuth 2.0 Client Credentials flow. Default: `"code"` `deprecated` `array[string]` values: `code`, `client_credentials`
~~`scope`~~ (query)	`string` This must be set to `openid` to indicate a request for OpenID authentication and ID token. Default: `"openid"` `deprecated`
~~`client_id`~~ (query)	`string` (required) This must be set to the client ID value obtained from the client application registration process in the developer portal. `deprecated`
~~`state`~~ (query)	`string` An arbitrary value set by the client to maintain state between the authorization request and the callback. `deprecated`
~~`redirect_uri`~~ (query)	`string` (required) The callback url for user redirection after successful login and consent with the Apiture Identity Provider. This value must match the value used during the client application registration process. The callback url is called with the authorization code provided as a parameter. Required if using the `authorization_code` flow. `deprecated`

Try It

Example responses

400 Response

422 Response

{
  "_profile": "https://production.api.apiture.com/schemas/common/errorResponse/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "Description of the error will appear here.",
    "statusCode": 422,
    "type": "specificErrorType",
    "attributes": {
      "value": "Optional attribute describing the error"
    },
    "remediation": "Optional instructions to remediate the error may appear here.",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://production.api.apiture.com/errors/specificErrorType"
      }
    },
    "_embedded": {
      "errors": {}
    }
  }
}

Responses

Status Description

302 Found

Complete the first phase of the Authorization Code flow. If the Location URI matches the redirect_uri parameter and contains a code, the client /authorize request was valid and the user successfully authenticated. If the client passed a state parameter, the client should parse the Location URI and verify that the state in the Location matches the request. (If not, someone may be trying to attack the client app and steal tokens.) The client should redirect to the URI in the Location response header. To complete the flow, that client request handler should save the code and pass it to createToken to get an access token.

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status	Description
401	Unauthorized
	Unauthorized. The user did not successfully authenticate.

Status	Description
422	Unprocessable Entity
	Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response contains details about the request error.
	Schema: `errorResponse`

Response Headers

Status	Description
`302`	`Location` `string` `uri`
	The redirect URI with additional parameters (`state` and `code`).

createToken

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -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
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: string

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  '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 inputBody = '{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json",
  "_links": {}
}';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json',
  'Authorization':'string',
  'API-Key':'API_KEY'

};

fetch('https://api.devbank.apiture.com/auth/oauth2/token',
{
  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/x-www-form-urlencoded',
  '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 = {
  'Content-Type': 'application/x-www-form-urlencoded',
  '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{
        "Content-Type": []string{"application/x-www-form-urlencoded"},
        "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~~

deprecated
Create or refresh an access token for client use. Depending on the value of the grant_type form parameter, this operation issues a new access token and a refresh token at the end of the initial authentication flow, or it can refresh an expired or expiring access token. Pass the parameters as form data using Content-Type: application/x-www-form-urlencoded.

To issue the initial token for interactive clients, use grant_type=authorization_code, passing the code obtained from the authorize operation and the redirect_uri query parameters. (Both the code and redirect_uri query parameters are required for this grant type.) Clients should save the refresh_token from the response.
For trusted (non-web, non-mobile) clients, use grant_type=client_credentials and the authorization header.
To refresh an expiring/expired access token, use grant_type=refresh_token refresh_token={refresh_token}, using the required {refresh_token} that was returned in the original oauthToken response from the earlier call to this operation.

All calls require the Authorization header.
Warning: The operation createToken was deprecated on version v0.29.1 of the API. Use the token_endpoint in the OpenID Connect configuration instead. createToken will be removed on version v0.35.0 of the API.

Body parameter

_profile: >-
  https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json
_links: {}

Parameters

Parameter	Description
~~`Authorization`~~ (header)	`string` (required) Authorization credentials in the form `Basic {encoded-credentials}` where `{encoded-credentials}` is a Base 64 encoding of the text `client-id:client-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. `deprecated`
`body` (body)	`tokenRequest` (required) The data necessary to request a token.

Try It

Example responses

200 Response

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

400 Response

Responses

Status	Description
200	OK
	Return a response containing the access token, refresh token, etc.
	Schema: `oauthToken`

Status	Description
302	Found
	Indicates a redirection url has been returned to the client.

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status Description

401 Unauthorized

The client did not include credentials or the credentials are not valid, or the access_token has expired and should be refreshed.

This error response may have one of the following type values:

accessDenied
createTokenAccessDenied

Schema: errorResponse

Status	Description
403	Forbidden
	Forbidden. The user or client is not allowed to perform this operation.
	Schema: `errorResponse`

Status	Description
422	Unprocessable Entity
	Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response contains details about the request error.
	Schema: `errorResponse`

Response Headers

Status	Description
`302`	`Location` `string`
	The login and consent page of the Apiture Identity Provider.

Passwords

User Authentication passwords

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 /passwordReset 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

Status	Description
202	Accepted
	Accepted.
	Schema: `passwordReset`

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status	Description
429	Too Many Requests
	Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP is blocked from further requests until a period of time has passed.
	Schema: `errorResponse`

Status	Description
500	Internal Server Error
	Server Error. Fatal error has occurred.
	Schema: `errorResponse`

sendPasswordResetInstructions

Code samples

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

POST https://api.devbank.apiture.com/auth/passwordResetInstructions 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',
  'Authorization':'Bearer {access-token}'

};

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

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

const fetch = require('node-fetch');
const inputBody = '{
  "_profile": "https://production.api.apiture.com/schemas/auth/passwordResetInstructions/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "emailAddress": "Casey.Hargrove@example.com",
  "userUri": "https://api.devbank.apiture.com/users/users/7460a72c-a602-464c-894e-9c463a81cc1d",
  "resetPasswordUri": "https://devbank.apiture.com/forgotPassword"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/passwordResetInstructions',
{
  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',
  'Authorization' => 'Bearer {access-token}'
}

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

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

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

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

Send password reset instructions to the user

POST /passwordResetInstructions

Send email or other communication to the user with instructions on how to reset their password. Operators use this when a user has contacted the financial institution and asks to change their password. This operation is reserved for operator (administrators) use.

Body parameter

{
  "_profile": "https://production.api.apiture.com/schemas/auth/passwordResetInstructions/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "emailAddress": "Casey.Hargrove@example.com",
  "userUri": "https://api.devbank.apiture.com/users/users/7460a72c-a602-464c-894e-9c463a81cc1d",
  "resetPasswordUri": "https://devbank.apiture.com/forgotPassword"
}

Parameters

Parameter	Description
`body` (body)	`passwordResetInstructions` (required) The data necessary to initiate email to the customer with password reset instructions.

Try It

Example responses

201 Response

{
  "_profile": "https://production.api.apiture.com/schemas/auth/passwordResetInstructions/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "emailAddress": "Casey.Hargrove@example.com",
  "userUri": "https://api.devbank.apiture.com/users/users/7460a72c-a602-464c-894e-9c463a81cc1d",
  "resetPasswordUri": "https://devbank.apiture.com/forgotPassword"
}

400 Response

Responses

Status	Description
201	Created
	OK.
	Schema: `passwordResetInstructions`

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status Description

422 Unprocessable Entity

Unprocessable Entity. The request body contains invalid data.

This error response may have one of the following type values:

emailNotFound
invalidUser

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://production.api.apiture.com/schemas/auth/confirmPasswordReset/v3.0.0/profile.json",
  "_links": {},
  "username": "john0224",
  "newPassword": "5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4",
  "confirmationCode": "12345",
  "_encryption": {
    "newPassword": "secret-48729783"
  }
}';
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 returns 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://production.api.apiture.com/schemas/auth/confirmPasswordReset/v3.0.0/profile.json",
  "_links": {},
  "username": "john0224",
  "newPassword": "5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4",
  "confirmationCode": "12345",
  "_encryption": {
    "newPassword": "secret-48729783"
  }
}

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

422 Response

{
  "_profile": "https://production.api.apiture.com/schemas/common/errorResponse/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "Description of the error will appear here.",
    "statusCode": 422,
    "type": "specificErrorType",
    "attributes": {
      "value": "Optional attribute describing the error"
    },
    "remediation": "Optional instructions to remediate the error may appear here.",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://production.api.apiture.com/errors/specificErrorType"
      }
    },
    "_embedded": {
      "errors": {}
    }
  }
}

Responses

Status	Description
202	Accepted
	Accepted.

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status Description

401 Unauthorized

The client did not include credentials or the credentials are not valid, or the access_token has expired and should be refreshed.

This error response may have one of the following type values:

accessDenied
createTokenAccessDenied

Schema: errorResponse

Status Description

422 Unprocessable Entity

Current password does not match or invalid new password.

This error response may have one of the following type values:

currentPasswordDoesNotMatch
invalidNewPassword
dataNotEncrypted

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: application/hal+json' \
  -H 'Apiture-Challenge: string' \
  -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: application/hal+json
Apiture-Challenge: string

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  'Apiture-Challenge':'string',
  '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 = '{
  "_profile": "https://production.api.apiture.com/schemas/auth/passwordChange/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "currentPassword": "dhjke45785huryur89rid7liuld8973hdodhwliw474hq4gp47h",
  "newPassword": "5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4",
  "_encryption": {
    "currentPassword": "secret-48729783",
    "newPassword": "secret-48729783"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  'Apiture-Challenge':'string',
  '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' => 'application/hal+json',
  'Apiture-Challenge' => 'string',
  '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': 'application/hal+json',
  'Apiture-Challenge': 'string',
  '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{"application/hal+json"},
        "Apiture-Challenge": []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/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 encrypt (see GET /encryptionKeys) and pass currentPassword and newPassword in the request body to change its password. This operation requires both apiKey and accessToken security. See Encryption for additional details.

This operation returns 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. This operation requires passing a valid Challenge ID in the Apiture-Challenge request header.

Body parameter

{
  "_profile": "https://production.api.apiture.com/schemas/auth/passwordChange/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "currentPassword": "dhjke45785huryur89rid7liuld8973hdodhwliw474hq4gp47h",
  "newPassword": "5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4",
  "_encryption": {
    "currentPassword": "secret-48729783",
    "newPassword": "secret-48729783"
  }
}

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 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

{
  "_profile": "https://production.api.apiture.com/schemas/auth/passwordChange/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "currentPassword": "dhjke45785huryur89rid7liuld8973hdodhwliw474hq4gp47h",
  "newPassword": "5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4",
  "_encryption": {
    "currentPassword": "secret-48729783",
    "newPassword": "secret-48729783"
  }
}

400 Response

Responses

Status	Description
200	OK
	OK. The response is used for the 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.

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status Description

401 Unauthorized

The client did not include credentials or the credentials are not valid, or the access_token has expired and should be refreshed.

This error response may have one of the following type values:

accessDenied
createTokenAccessDenied

Schema: errorResponse

Status Description

409 Conflict

Status	Description
409	Conflict
	Conflict. 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. This error response may have one of the following `type` values: `missingApitureChallengeHeader` `challengedNotVerified` `challengedExpired` `challengedAlreadyRedeemed`
	Schema: `challengeErrorResponse`

Conflict. 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.

This error response may have one of the following type values:

missingApitureChallengeHeader
challengedNotVerified
challengedExpired
challengedAlreadyRedeemed

Schema: challengeErrorResponse

Status Description

422 Unprocessable Entity

Current password does not match or invalid new password.

This error response may have one of the following type values:

currentPasswordDoesNotMatch
invalidNewPassword
dataNotEncrypted

Schema: errorResponse

Encryption

Data Encryption

getEncryptionKeys

Code samples

# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/encryptionKeys?keys=string \
  -H 'Accept: application/hal+json' \
  -H 'API-Key: API_KEY'

GET https://api.devbank.apiture.com/auth/encryptionKeys?keys=string HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/hal+json

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

};

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

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

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

};

fetch('https://api.devbank.apiture.com/auth/encryptionKeys?keys=string',
{
  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',
  'API-Key' => 'API_KEY'
}

result = RestClient.get 'https://api.devbank.apiture.com/auth/encryptionKeys',
  params: {
  'keys' => 'array[string]'
}, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.devbank.apiture.com/auth/encryptionKeys', params={
  'keys': [
  "string"
]
}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/encryptionKeys?keys=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{"application/hal+json"},
        "API-Key": []string{"API_KEY"},
        
    }

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

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

Get client-side encryption keys

GET /encryptionKeys

Get encryption keys that the client should use to encrypt sensitive data such as personally identifiable information (PII) and passwords. This adds security on top of transport layer security (TLS/HTTPS) so that sensitive data is not represented as plain text in request bodies. Clients should encrypt properties that have a x-apiture-encrypt: {keyName} annotation in the schema. The client adds metadata in an _encryption object next to the encrypted properties in the request body.

Parameters

Parameter Description

keys
(query) array[string] , comma (,) delimited items (required)
A list of encryption key names necessary to encrypt one or more properties in a request body. For example, if the request body schema contains two fields that are tagged x-apiture-encrypt: secret, use ?keys=secret. If the schema contain two fields, one encrypted with password and one with the key named pii, use ?keys=secret,pii.
minLength: 1

Parameter	Description
`keys` (query)	`array[string]` , comma (`,`) delimited items (required) A list of encryption key names necessary to encrypt one or more properties in a request body. For example, if the request body schema contains two fields that are tagged `x-apiture-encrypt: secret`, use `?keys=secret`. If the schema contain two fields, one encrypted with `password` and one with the key named `pii`, use `?keys=secret,pii`. `minLength: 1`

Try It

Example responses

200 Response

{
  "_profile": "https://production.api.apiture.com/schemas/common/encryptionKeys/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "keys": {
    "pii": {
      "name": "sensitive",
      "publicKey": "-----BEGIN RSA PUBLIC KEY-----\\nMIIBCgKCAQEAwh8kIf3rM4FtehDl+WM1egDdxccXFLNPBUvgpbAISnEh373M4vdN...\\n-----END RSA PUBLIC KEY-----",
      "alias": "sensitive-47839398",
      "createdAt": "2020-03-09T05:01:16.375Z",
      "expiresAt": "2020-03-09T05:01:53.375Z"
    },
    "secret": {
      "name": "secret",
      "publicKey": "-----BEGIN RSA PUBLIC KEY-----\\nMIIBCgKCAQEAl2/fCtf69EnMqw6O/6Wh9wFvKW80jjNfXEWbHh0cnWKW1i0Heg0B...\\n-----END RSA PUBLIC KEY-----",
      "alias": "secret-48729783",
      "createdAt": "2020-03-09T05:01:16.375Z",
      "expiresAt": "2020-03-09T05:01:53.375Z"
    }
  }
}

Responses

Status	Description
200	OK
	OK.
	Schema: `encryptionKeys`

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/) includes a link apiture:getDevices. This link's href resolves 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://production.api.apiture.com/schemas/auth/devices/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    },
    "collection": {
      "href": "/auth/users/testUser/devices"
    }
  },
  "start": 0,
  "limit": 100,
  "count": 1,
  "name": "devices",
  "_embedded": {
    "items": {
      "0": {
        "_profile": "https://production.api.apiture.com/schemas/auth/device/v1.1.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

Status	Description
200	OK
	OK.
	Schema: `Inline`

Status	Description
403	Forbidden
	Forbidden. The user or client is not allowed to perform this operation.
	Schema: `errorResponse`

Status Description

404 Not Found

The device was not found. The _error field in the response contains details about the request error.

This error response may have one of the following type values:

noSuchUser
noSuchDevice

Schema: errorResponse

Status	Description
429	Too Many Requests
	Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP is blocked from further requests until a period of time has passed.
	Schema: `errorResponse`

Status	Description
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. This schema was resolved from `common/links`.
»» Link (v1.0.0)	`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. This schema was resolved from `common/link`.
»»» 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 (v1.1.0)	`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. This schema was resolved from `common/links`.
»»»»» _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`.
»»»»»» 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 (v2.1.0)	`error` Describes an error in an API request or in a service called via the API. This schema was resolved from `common/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`.
»»»»»»»» 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. This schema was resolved from `common/links`.
»»»»»»» _links	`links` An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations. This schema was resolved from `common/links`.
»»»»»» _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 do 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`.
»»»»»» 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. This schema was resolved from `common/links`.
»»»»» 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://production.api.apiture.com/schemas/auth/device/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_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

Status	Description
200	OK
	OK.
	Schema: `Inline`

Status	Description
403	Forbidden
	Forbidden. The user or client is not allowed to perform this operation.
	Schema: `errorResponse`

Status Description

404 Not Found

The device was not found. The _error field in the response contains details about the request error.

This error response may have one of the following type values:

noSuchUser
noSuchDevice

Schema: errorResponse

Status	Description
429	Too Many Requests
	Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP is blocked from further requests until a period of time has passed.
	Schema: `errorResponse`

Status	Description
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. This schema was resolved from `common/links`.
»» Link (v1.0.0)	`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. This schema was resolved from `common/link`.
»»» 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`.
»»» 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 (v2.1.0)	`error` Describes an error in an API request or in a service called via the API. This schema was resolved from `common/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`.
»»»»» 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. This schema was resolved from `common/links`.
»»»» _links	`links` An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations. This schema was resolved from `common/links`.
»»» _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 do 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 should 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

404 Response

{
  "_profile": "https://production.api.apiture.com/schemas/common/errorResponse/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "Description of the error will appear here.",
    "statusCode": 422,
    "type": "specificErrorType",
    "attributes": {
      "value": "Optional attribute describing the error"
    },
    "remediation": "Optional instructions to remediate the error may appear here.",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://production.api.apiture.com/errors/specificErrorType"
      }
    },
    "_embedded": {
      "errors": {}
    }
  }
}

Responses

Status	Description
204	No Content
	No Content. The resource was deleted successfully.

Status	Description
403	Forbidden
	Forbidden. The user or client is not allowed to perform this operation.
	Schema: `errorResponse`

Status Description

404 Not Found

The device was not found. The _error field in the response contains details about the request error.

This error response may have one of the following type values:

noSuchUser
noSuchDevice

Schema: errorResponse

Status	Description
429	Too Many Requests
	Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP is blocked from further requests until a period of time has passed.
	Schema: `errorResponse`

Status	Description
500	Internal Server Error
	Server Error. Fatal error has occurred.
	Schema: `errorResponse`

Challenges

Identity Verification Challenges

redeemChallenge

Code samples

# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/redeemedChallenges?challenge=string \
  -H 'Accept: application/hal+json' \
  -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: application/hal+json
If-Match: string

var headers = {
  'Accept':'application/hal+json',
  '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':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+json"},
        "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

{
  "_profile": "https://production.api.apiture.com/schemas/auth/challenge/v1.2.0/profile.json",
  "_links": {
    "self": {
      "href": "/auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a"
    },
    "apiture:redeem": {
      "href": "/auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a"
    }
  },
  "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
  "reason": "Transfer amount much higher than normal",
  "contextUri": "https://fi.apiture.com/transfers/scheduledTransfers/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd",
  "minimumAuthenticatorCount": 1,
  "authenticators": {
    "0": {
      "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
      "_profile": "https://production.api.apiture.com/schemas/auth/authenticator/v1.2.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": {
            "0": "code",
            "1": "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"
}

Responses

Status	Description
200	OK
	OK. The operation succeeded. The challenge was updated and its `state` changed to `redeemed` and the `redeemedAt` timestamp updated.
	Schema: `challenge`

Status Description

400 Bad Request

Bad Request. The challenge parameter was malformed or does not refer to an existing or accessible challenge resource.

This error response may have one of the following type values:

challengeRefNotFound

Schema: errorResponse

Status Description

409 Conflict

Conflict. The request to redeem the challenged is not allowed. The _error field in the response contains details about the request error.

This error response may have one of the following type values:

redeemChallengeConflict

Schema: errorResponse

Status	Description
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

Status	Description
`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: application/hal+json' \
  -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: application/hal+json

var headers = {
  'Accept':'application/hal+json',
  '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':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+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/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. Default: `100`
`sortBy` (query)	`string` Optional sort criteria. See sort criteria format, such as `?sortBy=field1,-field2`. This collection may be sorted by the following properties:.
`filter` (query)	`string` Optional filter criteria. See filtering. This collection may be filtered by the following properties and functions: • Property `user` using functions `eq`, `ne`, `in` • Property `state` using functions `eq`, `ne`, `in`.
`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. `array[string]` values: `pending`, `started`, `verified`, `failed`, `redeemed`, `expired`

Try It

Example responses

200 Response

{
  "_profile": "https://production.api.apiture.com/schemas/auth/challenges/v1.1.0/profile.json",
  "_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"
    }
  },
  "start": 10,
  "limit": 10,
  "count": 67,
  "name": "challenges",
  "_embedded": {
    "items": {
      "0": {
        "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
        "_profile": "https://production.api.apiture.com/schemas/auth/challenge/v1.2.0/profile.json",
        "_links": {
          "self": {
            "href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c"
          }
        }
      },
      "1": {
        "_id": "d62c0701-0d74-4836-83f9-ebf3709442ea",
        "_profile": "https://production.api.apiture.com/schemas/auth/challenge/v1.2.0/profile.json",
        "_links": {
          "self": {
            "href": "/auth/challenges/d62c0701-0d74-4836-83f9-ebf3709442ea"
          }
        }
      }
    }
  }
}

400 Response

Responses

Status	Description
200	OK
	OK.
	Schema: `challenges`

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status	Description
422	Unprocessable Entity
	Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response contains 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: application/hal+json' \
  -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: application/hal+json

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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 = '{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractResource/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+json"},
        "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 contains 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 deletes 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

{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractResource/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  }
}

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 is not 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

{
  "_profile": "https://production.api.apiture.com/schemas/auth/challenge/v1.2.0/profile.json",
  "_links": {
    "self": {
      "href": "/auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a"
    },
    "apiture:redeem": {
      "href": "/auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a"
    }
  },
  "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
  "reason": "Transfer amount much higher than normal",
  "contextUri": "https://fi.apiture.com/transfers/scheduledTransfers/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd",
  "minimumAuthenticatorCount": 1,
  "authenticators": {
    "0": {
      "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
      "_profile": "https://production.api.apiture.com/schemas/auth/authenticator/v1.2.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": {
            "0": "code",
            "1": "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"
}

400 Response

Responses

Status	Description
201	Created
	Created.
	Schema: `challenge`

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status	Description
429	Too Many Requests
	Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP is blocked from further requests until a period of time has passed.
	Schema: `errorResponse`

Response Headers

Status	Description
`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: application/hal+json' \
  -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: application/hal+json
If-None-Match: string

var headers = {
  'Accept':'application/hal+json',
  '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':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+json"},
        "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` returns 304 (Not Modified) and no response body, else the resource representation is not returned.
`challengeId` (path)	`string` (required) The unique identifier of this challenge. This is an opaque string.

Try It

Example responses

200 Response

{
  "_profile": "https://production.api.apiture.com/schemas/auth/challenge/v1.2.0/profile.json",
  "_links": {
    "self": {
      "href": "/auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a"
    },
    "apiture:redeem": {
      "href": "/auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a"
    }
  },
  "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
  "reason": "Transfer amount much higher than normal",
  "contextUri": "https://fi.apiture.com/transfers/scheduledTransfers/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd",
  "minimumAuthenticatorCount": 1,
  "authenticators": {
    "0": {
      "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
      "_profile": "https://production.api.apiture.com/schemas/auth/authenticator/v1.2.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": {
            "0": "code",
            "1": "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"
}

Responses

Status	Description
200	OK
	OK.
	Schema: `challenge`

Status	Description
304	Not Modified
	Not Modified. The resource has not been modified since it was last fetched.

Status Description

404 Not Found

Not Found. There is no such challenge resource at the specified {challengeId}. The _error field in the response contains details about the request error.

This error response may have one of the following type values:

challengeNotFound

Schema: errorResponse

Response Headers

Status	Description
`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

Status	Description
204	No Content
	No Content. The resource was deleted successfully.

Authenticators

Identity Verification Authenticators

retryAuthenticator

Code samples

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

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

var headers = {
  'Accept':'application/hal+json',
  'If-Match':'string',
  'API-Key':'API_KEY'

};

$.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':'application/hal+json',
  'If-Match':'string',
  'API-Key':'API_KEY'

};

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' => 'application/hal+json',
  'If-Match' => 'string',
  'API-Key' => 'API_KEY'
}

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

p JSON.parse(result)

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

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{"application/hal+json"},
        "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/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

{
  "_profile": "https://production.api.apiture.com/schemas/auth/authenticator/v1.2.0/profile.json",
  "_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"
    }
  },
  "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
  "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
  "state": "started",
  "maskedTarget": "****1234",
  "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": {
        "0": "code",
        "1": "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"
}

Responses

Status	Description
200	OK
	OK. The operation succeeded. The authenticator was updated and its `state` changed to `started`.
	Schema: `authenticator`

Status Description

400 Bad Request

Bad Request. The authenticator parameter was malformed or does not refer to an existing or accessible authenticator.

This error response may have one of the following type values:

authenticatorRefNotFound

Schema: errorResponse

Status Description

409 Conflict

Conflict. The request to retry the authenticator is not allowed. The _error field in the response contains details about the request error.

This error response may have one of the following type values:

authenticatorAttemptsExceeded
invalidAuthenticatorState

Status	Description
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

Status	Description
`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: application/hal+json' \
  -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: application/hal+json
If-Match: string

var headers = {
  'Accept':'application/hal+json',
  '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':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+json"},
        "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 sends 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

{
  "_profile": "https://production.api.apiture.com/schemas/auth/authenticator/v1.2.0/profile.json",
  "_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"
    }
  },
  "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
  "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
  "state": "started",
  "maskedTarget": "****1234",
  "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": {
        "0": "code",
        "1": "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"
}

Responses

Status	Description
200	OK
	OK. The operation succeeded. The authenticator was updated and its `state` changed to `started`.
	Schema: `authenticator`

Status Description

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.

This error response may have one of the following type values:

authenticatorRefNotFound

Schema: errorResponse

Status Description

409 Conflict

Conflict. The request to start the authenticator is not allowed. The _error field in the response contains details about the request error.

This error response may have one of the following type values:

authenticatorAttemptsExceeded
invalidAuthenticatorState

Schema: errorResponse

Status	Description
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

Status	Description
`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: application/hal+json' \
  -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: application/hal+json
If-Match: string

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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 = '{
  "_profile": "https://production.api.apiture.com/schemas/auth/authenticator/v1.2.0/profile.json",
  "_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"
    }
  },
  "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
  "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
  "state": "started",
  "maskedTarget": "****1234",
  "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": {
        "0": "code",
        "1": "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"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+json"},
        "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

{
  "_profile": "https://production.api.apiture.com/schemas/auth/authenticator/v1.2.0/profile.json",
  "_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"
    }
  },
  "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
  "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
  "state": "started",
  "maskedTarget": "****1234",
  "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": {
        "0": "code",
        "1": "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"
}

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

{
  "_profile": "https://production.api.apiture.com/schemas/auth/authenticator/v1.2.0/profile.json",
  "_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"
    }
  },
  "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
  "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
  "state": "started",
  "maskedTarget": "****1234",
  "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": {
        "0": "code",
        "1": "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"
}

Responses

Status	Description
200	OK
	OK. The operation succeeded. The authenticator was updated and its `state` changed to `verified`.
	Schema: `authenticator`

Status Description

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.

This error response may have one of the following type values:

authenticatorRefNotFound

Schema: errorResponse

Status Description

409 Conflict

Conflict. The request to verify the authenticator is not allowed. The _error field in the response contains details about the request error.

This error response may have one of the following type values:

authenticatorNotCompletable
invalidAuthenticatorAttributes
invalidAuthenticatorState
authenticatorAttemptsExceeded

Schema: errorResponse

Status	Description
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

Status	Description
`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: application/hal+json' \
  -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: application/hal+json

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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 = '{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractResource/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+json"},
        "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

{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractResource/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  }
}

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

{
  "_profile": "https://production.api.apiture.com/schemas/auth/authenticator/v1.2.0/profile.json",
  "_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"
    }
  },
  "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
  "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
  "state": "started",
  "maskedTarget": "****1234",
  "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": {
        "0": "code",
        "1": "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"
}

Responses

Status	Description
201	Created
	Created.
	Schema: `authenticator`

Status Description

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.

This error response may have one of the following type values:

authenticatorRefNotFound

Schema: errorResponse

Status Description

404 Not Found

Not Found. There is no such challenge resource at the specified {challengeId}. The _error field in the response contains details about the request error.

This error response may have one of the following type values:

challengeNotFound

Schema: errorResponse

Response Headers

Status	Description
`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: application/hal+json' \
  -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: application/hal+json
If-None-Match: string

var headers = {
  'Accept':'application/hal+json',
  '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':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+json"},
        "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` returns 304 (Not Modified) and no response body, else the resource representation is not 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

{
  "_profile": "https://production.api.apiture.com/schemas/auth/authenticator/v1.2.0/profile.json",
  "_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"
    }
  },
  "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
  "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
  "state": "started",
  "maskedTarget": "****1234",
  "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": {
        "0": "code",
        "1": "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"
}

Responses

Status	Description
200	OK
	OK.
	Schema: `authenticator`

Status	Description
304	Not Modified
	Not Modified. The resource has not been modified since it was last fetched.

Status Description

404 Not Found

Not Found. There is no such authenticator resource at the specified {authenticatorId}. The _error field in the response contains details about the request error.

This error response may have one of the following type values:

authenticatorNotFound

Schema: errorResponse

Response Headers

Status	Description
`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

Status	Description
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: application/hal+json' \
  -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: application/hal+json

var headers = {
  'Accept':'application/hal+json',
  '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':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+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/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:

sms
email

Try It

Example responses

200 Response

{
  "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
        }
      }
    }
  }
}

Responses

Status	Description
200	OK
	OK.
	Schema: `authenticatorTypes`

Response Headers

Status	Description
`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: application/hal+json' \
  -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: application/hal+json
If-Match: string

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+json"},
        "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

{
  "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
        }
      }
    }
  }
}

400 Response

Responses

Status	Description
200	OK
	OK.
	Schema: `authenticatorTypes`

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status Description

409 Conflict

Conflict: The request body conflicts with existing state. The request must include (not remove) all types in use by existing authenticators/challenges.

This error response may have one of the following type values:

authenticatorTypeInUse

Schema: errorResponse

Status	Description
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

Status	Description
`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.

Users

User Management

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 = '{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json",
  "_links": {},
  "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

{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json",
  "_links": {},
  "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"
}

Responses

Status	Description
202	Accepted
	Accepted.
	Schema: `usernameRequestNotification`

Status Description

422 Unprocessable Entity

Username request is invalid.

This error response may have one of the following type values:

invalidUsernameRequest

Schema: errorResponse

Status	Description
429	Too Many Requests
	Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP is blocked from further requests until a period of time has passed.
	Schema: `errorResponse`

changeUsername

Code samples

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

PUT https://api.devbank.apiture.com/auth/my/username HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: application/hal+json
Apiture-Challenge: string

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  'Apiture-Challenge':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

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

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

const fetch = require('node-fetch');
const inputBody = '{
  "_profile": "https://production.api.apiture.com/schemas/auth/preferredUsername/v2.2.0/profile.json",
  "_links": {},
  "username": "john0224",
  "emailAddress": "JohnBankCustomer@example.com",
  "mobilePhone": "+19105550155"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  'Apiture-Challenge':'string',
  'API-Key':'API_KEY',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.devbank.apiture.com/auth/my/username',
{
  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' => 'application/hal+json',
  'Apiture-Challenge' => 'string',
  'API-Key' => 'API_KEY',
  'Authorization' => 'Bearer {access-token}'
}

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

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/hal+json',
  'Apiture-Challenge': 'string',
  'API-Key': 'API_KEY',
  'Authorization': 'Bearer {access-token}'
}

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

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/my/username");
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{"application/hal+json"},
        "Apiture-Challenge": []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/my/username", data)
    req.Header = headers

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

Change the username

PUT /my/username

Update the authenticated user's username. This operation requires passing a valid Challenge ID in the Apiture-Challenge request header.

Body parameter

{
  "_profile": "https://production.api.apiture.com/schemas/auth/preferredUsername/v2.2.0/profile.json",
  "_links": {},
  "username": "john0224",
  "emailAddress": "JohnBankCustomer@example.com",
  "mobilePhone": "+19105550155"
}

Parameters

Parameter	Description
`Apiture-Challenge` (header)	`string` (required) 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.
`body` (body)	`preferredUsername` (required) The user's preferred username.

Try It

Example responses

200 Response

{
  "_profile": "https://production.api.apiture.com/schemas/auth/preferredUsername/v2.2.0/profile.json",
  "_links": {},
  "username": "john0224",
  "emailAddress": "JohnBankCustomer@example.com",
  "mobilePhone": "+19105550155"
}

400 Response

Responses

Status	Description
200	OK
	OK.
	Schema: `preferredUsername`

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status Description

401 Unauthorized

The client did not include credentials or the credentials are not valid, or the access_token has expired and should be refreshed.

This error response may have one of the following type values:

accessDenied
createTokenAccessDenied

Schema: errorResponse

Status Description

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, the account has already been confirmed, or the username is already in use.

This error response may have one of the following type values:

missingApitureChallengeHeader
challengedNotVerified
challengedExpired
challengedAlreadyRedeemed
invalidUsername
accountAlreadyConfirmed
duplicateUsername

Schema: challengeErrorResponse

Status Description

422 Unprocessable Entity

Unprocessable Entity. The challenge parameter was malformed or does not refer to an existing or accessible challenge resource, or the username does not meet the minimum requirements.

This error response may have one of the following type values:

challengeRefNotFound
invalidNewUsername
invalidSymbolForNonEmailUsernameFormat

Schema: errorResponse

Status	Description
429	Too Many Requests
	Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP is 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: application/hal+json' \
  -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: application/hal+json

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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://production.api.apiture.com/schemas/auth/userConfirmation/v2.0.0/profile.json",
  "_links": {},
  "firstName": "John",
  "lastName": "Smith",
  "birthdate": "1975-28-02",
  "taxId": "{encrypted-version-of-users-aaa-bb-cccc-taxId}",
  "captcha": {
    "id": "e44c8ae6-8504-4bb8-bcb3-65066722c2ea",
    "vendor": "google",
    "type": "reCaptcha3"
  },
  "_encryption": {
    "taxId": "sensitive-48729783"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+json"},
        "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), complete a CAPTCHA, and submit the data here. A successful operation (the request was well formed) returns a Challenge resource. The system connects the user resource to that customer in the banking core and creates a new login account.

The client should then use one of the returned challenge's authenticators to verify their identity (i.e. complete multi-factor authentication). If verified, the user enters their new username in the client application. The client should then use the createUsername operation to validate and submit the user's new username to create the user's login account.

Note that the client must encrypt the taxId in the request body using client-side asymmetric encryption. See Encryption for additional details.

Body parameter

{
  "_profile": "https://production.api.apiture.com/schemas/auth/userConfirmation/v2.0.0/profile.json",
  "_links": {},
  "firstName": "John",
  "lastName": "Smith",
  "birthdate": "1975-28-02",
  "taxId": "{encrypted-version-of-users-aaa-bb-cccc-taxId}",
  "captcha": {
    "id": "e44c8ae6-8504-4bb8-bcb3-65066722c2ea",
    "vendor": "google",
    "type": "reCaptcha3"
  },
  "_encryption": {
    "taxId": "sensitive-48729783"
  }
}

Parameters

Parameter	Description
`body` (body)	`userConfirmation` (required)

Try It

Example responses

200 Response

{
  "_profile": "https://production.api.apiture.com/schemas/auth/userConfirmationResponse/v1.3.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "queryResult": "matched",
  "challenge": {
    "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
    "_profile": "https://production.api.apiture.com/schemas/auth/challenge/v1.2.0/profile.json",
    "reason": "Transfer amount much higher than normal",
    "contextUri": "https://fi.apiture.com/transfers/scheduledTransfers/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd",
    "minimumAuthenticatorCount": 1,
    "authenticators": {}
  }
}

400 Response

Responses

Status	Description
200	OK
	OK. The response does not indicate if an existing user matching the data exists or not.
	Schema: `userConfirmationResponse`

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status Description

422 Unprocessable Entity

Unprocessable Entity. The request syntax was valid, but the data cannot be processed.

This error response may have one of the following type values:

expiredCaptcha
invalidCaptcha
captchaThresholdNotMet
captchaAlreadySubmitted
dataNotEncrypted

Schema: errorResponse

Status	Description
429	Too Many Requests
	Too Many Requests. If the threshold for number of requests from an IP address is exceeded, the IP is blocked from further requests until a period of time has passed.
	Schema: `errorResponse`

createUsername

Code samples

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

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

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

};

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

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

const fetch = require('node-fetch');
const inputBody = '{
  "_profile": "https://production.api.apiture.com/schemas/auth/preferredUsername/v2.2.0/profile.json",
  "_links": {},
  "username": "john0224",
  "emailAddress": "JohnBankCustomer@example.com",
  "mobilePhone": "+19105550155"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  'Apiture-Challenge':'string',
  'API-Key':'API_KEY'

};

fetch('https://api.devbank.apiture.com/auth/username',
{
  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/hal+json',
  'Apiture-Challenge' => 'string',
  'API-Key' => 'API_KEY'
}

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

URL obj = new URL("https://api.devbank.apiture.com/auth/username");
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/hal+json"},
        "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/username", data)
    req.Header = headers

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

Assign a username for a new digital banking platform user

POST /username

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

If there are no errors in the request, the Authentication service returns a temporary password to the user. The user should login with the temporary password, then change the password to one of their choosing.

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 lists 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://production.api.apiture.com/schemas/auth/preferredUsername/v2.2.0/profile.json",
  "_links": {},
  "username": "john0224",
  "emailAddress": "JohnBankCustomer@example.com",
  "mobilePhone": "+19105550155"
}

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)	`preferredUsername` (required) The user's preferred username.

Try It

Example responses

200 Response

{
  "_profile": "https://production.api.apiture.com/schemas/auth/preferredUsernameResponse/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "temporaryPassword": "#pbw+`XNtwPf5,K7"
}

400 Response

Responses

Status Description

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 lists validation errors, if any.

This error response may have one of the following type values:

invalidNewPassword
invalidUsername

Schema: preferredUsernameResponse

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status Description

409 Conflict

This error response may have one of the following type values:

missingApitureChallengeHeader
challengedNotVerified
challengedExpired
challengedAlreadyRedeemed
invalidUsername
accountAlreadyConfirmed
duplicateUsername

Schema: challengeErrorResponse

Status Description

422 Unprocessable Entity

Unprocessable Entity. The challenge parameter was malformed or does not refer to an existing or accessible challenge resource, or the username does not meet the minimum requirements.

This error response may have one of the following type values:

challengeRefNotFound
invalidNewUsername
invalidSymbolForNonEmailUsernameFormat

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: application/hal+json' \
  -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: application/hal+json

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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://production.api.apiture.com/schemas/auth/userSessionStart/v1.0.1/profile.json",
  "_links": {},
  "mfa": {
    "performed": true,
    "tryCount": 1
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+json"},
        "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 identifier 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://production.api.apiture.com/schemas/auth/userSessionStart/v1.0.1/profile.json",
  "_links": {},
  "mfa": {
    "performed": true,
    "tryCount": 1
  }
}

Parameters

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

Try It

Example responses

202 Response

{
  "_profile": "https://production.api.apiture.com/schemas/auth/userSession/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}

400 Response

Responses

Status	Description
202	Accepted
	Accepted.
	Schema: `userSession`

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status	Description
422	Unprocessable Entity
	Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response contains details about the request error.
	Schema: `errorResponse`

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: application/hal+json' \
  -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: application/hal+json

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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://production.api.apiture.com/schemas/auth/userSession/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/hal+json',
  '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' => 'application/hal+json',
  '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': 'application/hal+json',
  '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{"application/hal+json"},
        "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://production.api.apiture.com/schemas/auth/userSession/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_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

{
  "_profile": "https://production.api.apiture.com/schemas/auth/userSession/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}

400 Response

Responses

Status	Description
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`

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status Description

404 Not Found

Not Found. The session does not exist.

This error response may have one of the following type values:

invalidSession

Schema: errorResponse

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://production.api.apiture.com/schemas/auth/userSession/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_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://production.api.apiture.com/schemas/auth/userSession/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_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

404 Response

{
  "_profile": "https://production.api.apiture.com/schemas/common/errorResponse/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "Description of the error will appear here.",
    "statusCode": 422,
    "type": "specificErrorType",
    "attributes": {
      "value": "Optional attribute describing the error"
    },
    "remediation": "Optional instructions to remediate the error may appear here.",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://production.api.apiture.com/errors/specificErrorType"
      }
    },
    "_embedded": {
      "errors": {}
    }
  }
}

Responses

Status	Description
204	No Content
	No Content.

Status	Description
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 contains details about the request error.
	Schema: `errorResponse`

Status	Description
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: `errorResponse`

API

The Authentication API

getLabels

Code samples

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

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

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

};

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

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

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

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

};

fetch('https://api.devbank.apiture.com/auth/labels',
{
  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',
  'Accept-Language' => 'string',
  'API-Key' => 'API_KEY'
}

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

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

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

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

Localized Labels

GET /labels

Return a JSON object which defines labels for enumeration types defined by the schemas defined in this API. The labels in the response may not all match the requested language; some may be in the default language (en-us).

Parameters

Parameter	Description
`Accept-Language` (header)	`string` The weighted language tags which indicate the user's preferred natural language for the localized labels in the response, as per RFC 7231.

Try It

Example responses

200 Response

{
  "unknown": {
    "label": "Unknown",
    "code": "0",
    "hidden": true
  },
  "under1Million": {
    "label": "Under $1M",
    "code": "1",
    "range": "[0,1000000.00)",
    "variants": {
      "fr": {
        "label": "Moins de $1M"
      }
    }
  },
  "from1to10Million": {
    "label": "$1M to $10M",
    "code": "2",
    "range": "[1000000.00,10000000.00)",
    "variants": {
      "fr": {
        "label": "$1M \\u00e0 $10M"
      }
    }
  },
  "from10to100Million": {
    "label": "$10M to $100M",
    "code": "3",
    "range": "[10000000.00,100000000.00)",
    "variants": {
      "fr": [
        "label $10M \\u00e0 $100M"
      ]
    }
  },
  "over100Million": {
    "label": "Over $100,000,000.00",
    "code": "4",
    "range": "[100000000.00,]",
    "variants": {
      "fr": {
        "label": "Plus de $10M"
      }
    }
  },
  "other": {
    "label": "Other",
    "code": 254
  }
}

Responses

Status	Description
200	OK
	OK.
	Schema: `labelGroup`

getApi

Code samples

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

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',
  'API-Key':'API_KEY'

};

$.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',
  'API-Key':'API_KEY'

};

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',
  'API-Key' => 'API_KEY'
}

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

p JSON.parse(result)

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

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"},
        "API-Key": []string{"API_KEY"},
        
    }

    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.

The response includes two additional _links to allow OpenID Connect discovery.

The apiture:issuer link's href is the URL of the OpenID Connect issuer
The apiture:openIdConfiguration link's href is the URL of the OpenID Connect configuration data.

Try It

Example responses

OK.

{
  "id": "auth",
  "name": "Authorization",
  "apiVersion": "0.1.0",
  "_profile": "https://production.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

{
  "_profile": "https://production.api.apiture.com/schemas/common/root/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "id": "apiName",
  "name": "API name",
  "apiVersion": "1.0.0"
}

Responses

Status	Description
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' \
  -H 'API-Key: API_KEY'

GET https://api.devbank.apiture.com/auth/apiDoc 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/apiDoc',
  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/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',
  'API-Key' => 'API_KEY'
}

result = RestClient.get 'https://api.devbank.apiture.com/auth/apiDoc',
  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/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"},
        "API-Key": []string{"API_KEY"},
        
    }

    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

Status	Description
200	OK
	OK.
	Schema: `Inline`

Response Schema

Schemas

abstractRequest

{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json",
  "_links": {}
}

Abstract Request (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.

This schema was resolved from common/abstractRequest.

Properties

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.

This schema was resolved from common/links.

_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.
read-only

abstractResource

{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractResource/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  }
}

Abstract Resource (v2.1.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.

This schema was resolved from common/abstractResource.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`

attributes

{}

Attributes (v2.1.0)

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

This schema was resolved from common/attributes.

Properties

authenticationCaptcha

{
  "id": "e44c8ae6-8504-4bb8-bcb3-65066722c2ea",
  "vendor": "google",
  "type": "reCaptcha3"
}

Authentication Captcha (v1.0.0)

The completed client-side CAPTCHA (Completely Automatic Public Turing Test to Tell Computers and Humans Apart) which established the request as a valid interactive request. The service will verify this data to ensure only valid clients call this operation.

Properties

Name Description

type string (required)
The type of CAPTCHA which established the request as a valid interactive request. Typical values may be reCaptcha3 or reCaptcha2.
minLength: 4
maxLength: 20
pattern: ^[a-z][a-zA-Z0-9]{3,20}$

id string (required)
The ID of a completed client-side CAPTCHA which established the request as a valid interactive request.

vendor

string (required)

The name of the CAPTCHA provider. Supported vendors are currently:

google for Google reCaptcha v3.

minLength: 4
maxLength: 20
pattern: ^[a-z][a-zA-Z0-9]{3,20}$

authenticator

{
  "_profile": "https://production.api.apiture.com/schemas/auth/authenticator/v1.2.0/profile.json",
  "_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"
    }
  },
  "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
  "userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
  "state": "started",
  "maskedTarget": "****1234",
  "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": {
        "0": "code",
        "1": "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"
}

Authenticator (v1.2.0)

Representation of authenticators which verify a user's identity.

Links

Response and request bodies using this authenticator schema may contain the following links:

Rel	Summary	Method
`apiture:retry`	Retry an authenticator	`POST`
`apiture:start`	Start an authenticator	`POST`
`apiture:verify`	Verify a user's identity	`POST`
`apiture:challenge`	Fetch a representation of this challenge	`GET`

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`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`
`maskedTarget`	`string` A masked value which helps identify the specific authenticator target, such as a masked mobile phone or a masked email address.
`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`

authenticatorCategory

"knowledge"

authenticatorCategory (v1.0.0)

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.

authenticatorCategory strings may have one of the following enumerated values:

Value	Description
`knowledge`	Knowledge: Authenticate with information the user knows, such as a password or answers to personal questions.
`biometric`	Biometric: Authenticate with physical characteristics of the user, such as fingerprints, voiceprint, or faceprint.
`device`	Device: Authenticate with a device that the user has, such as a mobile phone or an electronic key.

These enumeration values are further described by the label group named authenticatorCategory in the response from the getLabels operation.

Type: string
Enumerated values:
knowledge
biometric
device

authenticatorState

"pending"

Authenticator State (v1.0.0)

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.

authenticatorState strings may have one of the following enumerated values:

Value	Description
`pending`	Pending: The authenticator is created but not yet started.
`started`	Started: The user has started the authenticator.
`verified`	Verified: The user corresponding verified the authenticator.
`failed`	Failed: The user failed the authenticators criteria.
`expired`	Expired: The authenticator expired before the user completed the criteria.

These enumeration values are further described by the label group named authenticatorState in the response from the getLabels operation.

Type: string
Enumerated values:
pending
started
verified
failed
expired

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 (v1.0.0)

An authenticator type description.

Properties

Name	Description
`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.

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 (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

Name	Description
`additionalProperties`	`authenticatorType` An authenticator type description.

challenge

{
  "_profile": "https://production.api.apiture.com/schemas/auth/challenge/v1.2.0/profile.json",
  "_links": {
    "self": {
      "href": "/auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a"
    },
    "apiture:redeem": {
      "href": "/auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a"
    }
  },
  "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
  "reason": "Transfer amount much higher than normal",
  "contextUri": "https://fi.apiture.com/transfers/scheduledTransfers/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd",
  "minimumAuthenticatorCount": 1,
  "authenticators": {
    "0": {
      "_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
      "_profile": "https://production.api.apiture.com/schemas/auth/authenticator/v1.2.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": {
            "0": "code",
            "1": "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"
}

Challenge (v1.2.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).

Links

Response and request bodies using this challenge schema may contain the following links:

Rel	Summary	Method
`apiture:redeem`	Redeem or use a challenge	`POST`

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`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(uri)` 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. `maxLength: 2048`
`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`
`code`	`string` An optional authentication code which is only returned in the challenge resource if both a) the platform assigned the `code` when constructing the challenge), and b) the user has successfully verified the challenge. The client must re-fetch the verified challenge in order to access this property. `read-only` `minLength: 16` `maxLength: 128`

challengeError

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

Challenge Error (v1.2.0)

The operation error description with an embedded identity challenge.

Properties

Name	Description
`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. This schema was resolved from `common/links`.
`_embedded`	`object` Embedded objects
`» challenge`	`challenge` The details of the identity verification challenge.

challengeErrorResponse

{
  "_profile": "https://production.api.apiture.com/schemas/common/errorResponse/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "Description of the error will appear here.",
    "statusCode": 422,
    "type": "specificErrorType",
    "attributes": {
      "value": "Optional attribute describing the error"
    },
    "remediation": "Optional instructions to remediate the error may appear here.",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://production.api.apiture.com/errors/specificErrorType"
      }
    },
    "_embedded": {
      "errors": {}
    }
  }
}

Challenge Error Response (v1.2.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

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`challengeError` The description of the error.

challengeState

"pending"

Challenge States (v1.0.0)

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

challengeState strings may have one of the following enumerated values:

Value	Description
`pending`	Pending: The challenge is created but not yet started.
`started`	Started: The user has started the challenge and associated authenticator(s).
`verified`	Verified: The user correctly verified the corresponding authenticator(s), marking the challenge as verified.
`failed`	Failed: The challenge has failed, often because the user failed one or more of the authenticators.
`redeemed`	Redeemed: The user has redeemed (used) the challenge.
`expired`	Expired: The challenge has expired without being verified.

These enumeration values are further described by the label group named challengeState in the response from the getLabels operation.

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

challenges

{
  "_profile": "https://production.api.apiture.com/schemas/auth/challenges/v1.1.0/profile.json",
  "_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"
    }
  },
  "start": 10,
  "limit": 10,
  "count": 67,
  "name": "challenges",
  "_embedded": {
    "items": {
      "0": {
        "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
        "_profile": "https://production.api.apiture.com/schemas/auth/challenge/v1.2.0/profile.json",
        "_links": {
          "self": {
            "href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c"
          }
        }
      },
      "1": {
        "_id": "d62c0701-0d74-4836-83f9-ebf3709442ea",
        "_profile": "https://production.api.apiture.com/schemas/auth/challenge/v1.2.0/profile.json",
        "_links": {
          "self": {
            "href": "/auth/challenges/d62c0701-0d74-4836-83f9-ebf3709442ea"
          }
        }
      }
    }
  }
}

Challenge Collection (v1.1.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

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`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.

collection

{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractResource/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  }
}

Collection (v2.1.0)

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

This schema was resolved from common/collection.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`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.

confirmPasswordReset

{
  "_profile": "https://production.api.apiture.com/schemas/auth/confirmPasswordReset/v3.0.0/profile.json",
  "_links": {},
  "username": "john0224",
  "newPassword": "5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4",
  "confirmationCode": "12345",
  "_encryption": {
    "newPassword": "secret-48729783"
  }
}

Confirm Password Reset (v3.0.0)

Representation used to confirm a password reset flow. The newPassword must be encrypted and Base64 encoded; see Encryption for additional details.

The value of confirmPasswordReset in requests must be encrypted with the [object Object] encryption key.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`newPassword`	`string(encrypted-password)` (required) The user's encrypted new password. The client should prompt the user for their new password, then encrypt it with the `secret` encryption key.
`confirmationCode`	`string` (required) A confirmation code send when the user initiated password reset.
`username`	`string(username)` (required) The username. `minLength: 2` `maxLength: 64`
`_encryption`	`encryptionMetadata` (required) Metadata about the encrypted `newPassword` property.

createAuthenticator

{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractResource/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  }
}

Create Authenticator (v1.1.0)

A request to create a new authenticator.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`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`

createChallenge

{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractResource/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  }
}

Create Challenge (v1.1.0)

A request to create a user authentication challenge.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`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(uri)` (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. `maxLength: 2048`
`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`
`code`	`string` An optional opaque code string which a service may assign when using the Challenge API to satisfy the deployment's authentication challenge. This code is returned in the challenge resource only when the user has successfully verified the challenge. The client may use this code to complete the authentication provider's authentication flow. `minLength: 16` `maxLength: 128`

device

{
  "_profile": "https://production.api.apiture.com/schemas/auth/device/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_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 (v1.1.0)

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

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`_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 do 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://production.api.apiture.com/schemas/auth/devices/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    },
    "collection": {
      "href": "/auth/users/testUser/devices"
    }
  },
  "start": 0,
  "limit": 100,
  "count": 1,
  "name": "devices",
  "_embedded": {
    "items": {
      "0": {
        "_profile": "https://production.api.apiture.com/schemas/auth/device/v1.1.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 (v1.1.0)

A collection of devices which user uses to sign in.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`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.

encryptionKey

{
  "name": "secret",
  "publicKey": "-----BEGIN RSA PUBLIC KEY-----\\nMIIBCgKCAQEAl2/fCtf69EnMqw6O/6Wh9wFvKW80jjNfXEWbHh0cnWKW1i0Heg0B...\\n-----END RSA PUBLIC KEY-----",
  "alias": "secret-48729783",
  "createdAt": "2020-03-09T05:01:16.375Z",
  "expiresAt": "2020-03-09T05:01:53.375Z"
}

Encryption Key (v1.0.1)

A rotating public encryption key. See Encryption for additional details.

This schema was resolved from common/encryptionKey.

Properties

Name	Description
`name`	`encryptionKeyName` The name of an encryption key; this identifies the type of data the key encrypts, such as `pii` for personally identifying information, `secret` for passwords or other secret data. The type name is taken from the `x-apiture-encrypt` annotation on the property in the JSON schema or chosen by the client when requesting encryption keys.
`publicKey`	`string` The ASCII encoded public encryption key that the client uses to encrypt data. This is half of the asymmetric public/private key pair. This is a mult-line string with key bopokends and embedded line breaks.
`alias`	`string` An alias for the actual rotating key. Keys rotate every few minutes. The alias identifies a specific instance of an active public/private key pair. This alias must be set in the `_encryption` metadata (see `encryptionMetadata`). The value of the alias is the concatenation of the `name`, a dash `-`, and some additional characters which identify the specific key rotation. `minLength: 6` `maxLength: 19` `pattern: ^[a-z][a-zA-Z0-9]{2,11}-.{2,8}$`
`createdAt`	`string(date-time)` The date-time when the encryption key was created, in RFC 3339 date-time format.
`expiresAt`	`string(date-time)` The date-time when the encryption key will expire. If this expiration time has passed or is less than 60 seconds away, the client should fetch updated encryption keys. RFC 3339 date-time format.

encryptionKeyName

"secret"

Encryption Key Name (v1.0.1)

An encryption key name identifies the type of data that the client wishes to encrypt, such as pii for personally identifying information, secret for passwords or other secret data. The type name is taken from the x-apiture-encrypt annotation on the property in the JSON schema or chosen by the client when requesting encryption keys.

This schema was resolved from common/encryptionKeyName.

Properties

encryptionKeys

{
  "_profile": "https://production.api.apiture.com/schemas/common/encryptionKeys/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "keys": {
    "pii": {
      "name": "sensitive",
      "publicKey": "-----BEGIN RSA PUBLIC KEY-----\\nMIIBCgKCAQEAwh8kIf3rM4FtehDl+WM1egDdxccXFLNPBUvgpbAISnEh373M4vdN...\\n-----END RSA PUBLIC KEY-----",
      "alias": "sensitive-47839398",
      "createdAt": "2020-03-09T05:01:16.375Z",
      "expiresAt": "2020-03-09T05:01:53.375Z"
    },
    "secret": {
      "name": "secret",
      "publicKey": "-----BEGIN RSA PUBLIC KEY-----\\nMIIBCgKCAQEAl2/fCtf69EnMqw6O/6Wh9wFvKW80jjNfXEWbHh0cnWKW1i0Heg0B...\\n-----END RSA PUBLIC KEY-----",
      "alias": "secret-48729783",
      "createdAt": "2020-03-09T05:01:16.375Z",
      "expiresAt": "2020-03-09T05:01:53.375Z"
    }
  }
}

Encryption Keys (v1.1.0)

A set of rotating public encryption keys that the client may use to encrypt sensitive or secret data before sending it to the service. The client only has access to the public key and only the service can decrypt the data. Such keys typically expire after several minutes.

This schema was resolved from common/encryptionKeys.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`keys`	`object` A map of encryption keys. The map's keys are the key `name`; the values are encryption key objects.
`» additionalProperties`	`encryptionKey` A rotating public encryption key. See Encryption for additional details. This schema was resolved from `common/encryptionKey`.

encryptionMetadata

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

Enryption Metadata (v1.0.1)

Metadata about encrypted data within a JSON object in a request body. This _encryption object is a peer of the encrypted data. Each nested object that contains encrypted properties has it's own _encryption object.

This object is a map of string property names → string encryption key alias. The keys are names of the encrypted and Base64 encoded property. Each value is the alias of the rotating public encryption key that the client used to encrypt the named property. See Encryption for additional details.

This schema was resolved from common/encryptionMetadata.

Properties

Name	Description
`additionalProperties`	`string`

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 (v2.1.0)

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

This schema was resolved from common/error.

Properties

Name	Description
`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. This schema was resolved from `common/links`.

errorResponse

{
  "_profile": "https://production.api.apiture.com/schemas/common/errorResponse/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "message": "Description of the error will appear here.",
    "statusCode": 422,
    "type": "specificErrorType",
    "attributes": {
      "value": "Optional attribute describing the error"
    },
    "remediation": "Optional instructions to remediate the error may appear here.",
    "occurredAt": "2018-01-25T05:50:52.375Z",
    "_links": {
      "describedby": {
        "href": "https://production.api.apiture.com/errors/specificErrorType"
      }
    },
    "_embedded": {
      "errors": {}
    }
  }
}

Error Response (v2.1.0)

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

This schema was resolved from common/errorResponse.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`

gpsCoordinates

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

GPS Coordinates (v1.0.0)

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

Properties

Name	Description
`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`

labelGroup

{
  "unknown": {
    "label": "Unknown",
    "code": "0",
    "hidden": true
  },
  "under1Million": {
    "label": "Under $1M",
    "code": "1",
    "range": "[0,1000000.00)",
    "variants": {
      "fr": {
        "label": "Moins de $1M"
      }
    }
  },
  "from1to10Million": {
    "label": "$1M to $10M",
    "code": "2",
    "range": "[1000000.00,10000000.00)",
    "variants": {
      "fr": {
        "label": "$1M \\u00e0 $10M"
      }
    }
  },
  "from10to100Million": {
    "label": "$10M to $100M",
    "code": "3",
    "range": "[10000000.00,100000000.00)",
    "variants": {
      "fr": [
        "label $10M \\u00e0 $100M"
      ]
    }
  },
  "over100Million": {
    "label": "Over $100,000,000.00",
    "code": "4",
    "range": "[100000000.00,]",
    "variants": {
      "fr": {
        "label": "Plus de $10M"
      }
    }
  },
  "other": {
    "label": "Other",
    "code": 254
  }
}

Label Group (v1.0.0)

A map that defines labels for the items in a group. This is a map from each item name → a labelItem object. For example, consider a JSON response that includes a property named revenueEstimate; the values for revenueEstimate must be one of the items in the group named estimatedAnnualRevenue, with options ranging under1Million, to over100Million. The item name is used as the selected value in an Apiture representation, such as { ..., "revenueEstimate" : "from10to100Million" , ...}, and the item with the name from10to100Million defines the presentation labels for that item, as well as other metadata about that choice: this is the range [10000000.00,100000000.00).

This allows the client to let the user select a value from a list, such as the following derived from the labels in the example:

Unknown
Under $1M
$1M to $10M
$10M to $100M
$100M or more

Note that the other item is hidden from the selection list, as that item is marked as hidden. For items which define numeric ranges, a client may instead let the customer directly enter their estimated annual revenue as a number, such as 4,500,000.00. The client can then match that number to one of ranges in the items and set the revenueEstimate to the corresponding item's name: { ..., "revenueEstimate" : "from1to10Million", ... }.

This schema was resolved from common/labelGroup.

Properties

Name Description

additionalProperties

labelItem
An item in a labelGroup, with a set of variants which contains different localized labels for the item. Each (simpleLabel) variant defines the presentation text label and optional description for a language. Items may also have a lookup code to map to external syststems, a numeric range, and a hidden boolean to indicate the item is normally hidden in the UI.

This schema was resolved from common/labelItem.

labelItem

{
  "over100Million": {
    "label": "Over $100,000,000.00",
    "code": "4",
    "range": "[100000000.00,]",
    "variants": {
      "fr": {
        "label": "Plus de $10M"
      }
    }
  }
}

Label Item (v1.0.0)

An item in a labelGroup, with a set of variants which contains different localized labels for the item. Each (simpleLabel) variant defines the presentation text label and optional description for a language. Items may also have a lookup code to map to external syststems, a numeric range, and a hidden boolean to indicate the item is normally hidden in the UI.

This schema was resolved from common/labelItem.

Properties

Name	Description
`label`	`string` (required) A label or title which may be used as labels or other UI controls which present a value.
`description`	`string` A more detailed localized description of a localizable label.
`variants`	`object` The language-specific variants of this label. The keys in this object are RFC 7231 language codes.
`» additionalProperties`	`simpleLabel` A text label and optional description. This schema was resolved from `common/simpleLabel`.
`code`	`string` If the localized value is associated with an external standard or definition, this is a lookup code or key or URI for that value. `minLength: 1`
`hidden`	`boolean` If `true`, this item is normally hidden from the User Interface.
`range`	`string` The range of values, if the item describes a bounded numeric value. This is range notation such as `[min,max]`, `(exclusiveMin,max]`, `[min,exclusiveMax)`, or `(exclusiveMin,exclusiveMax)`. For example, `[0,100)` is the range greater than or equal to 0 and less than 100. If the min or max value are omitted, that end of the range is unbounded. For example, `(,1000.00)` means less than 1000.00 and `[20000.00,]` means 20000.00 or more. The ranges do not overlap or have gaps. `pattern: ^[\[$](-?(0\|[1-9][0-9])(\.[0-9]+)?)?,(-?(0\|[1-9][0-9])(\.[0-9]+)?)?[\]$]$`

link

{
  "href": "https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
  "title": "Application"
}

Link (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.

This schema was resolved from common/link.

Properties

Name	Description
`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.

links

{
  "property1": {
    "href": "https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
    "title": "Application"
  },
  "property2": {
    "href": "https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
    "title": "Application"
  }
}

Links (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.

This schema was resolved from common/links.

Properties

Name Description

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.

This schema was resolved from common/link.

mobileDevice

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

Mobile Device (v1.0.0)

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

Properties

Name	Description
`_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

oauthToken

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

OAuth Tokens (v1.0.1)

A response from a credentialed request for tokens.

Properties

Name	Description
`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, using 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.

passwordChange

{
  "_profile": "https://production.api.apiture.com/schemas/auth/passwordChange/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "currentPassword": "dhjke45785huryur89rid7liuld8973hdodhwliw474hq4gp47h",
  "newPassword": "5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4",
  "_encryption": {
    "currentPassword": "secret-48729783",
    "newPassword": "secret-48729783"
  }
}

Password change (v2.1.0)

Representation used to change a user password. The request must contain the currentPassword, the newPassword. The client encrypts and Base64 encodes these values using the secret encryption key and stores the corresponding encryption key aliases in the _encryption metadata property. See Encryption for additional details.

The value of passwordChange in requests must be encrypted with the [object Object] encryption key.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`currentPassword`	`string(encrypted-password)` (required) The user's current encrypted user password. The client should prompt the user for their current password, then encrypt it with the `secret` encryption key.
`newPassword`	`string(encrypted-password)` (required) The user's encrypted new password. The client should prompt the user for their new password, then encrypt it with the `secret` encryption key.
`_encryption`	`encryptionMetadata` (required) Metadata about the encrypted `currentPassword` and `newPassword` properties.

passwordReset

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

Password Reset (v1.0.0)

Password reset resource.

Properties

Name	Description
`codeDeliveryMethod`	`string` Confirmation code delivery method. Enumerated values: `sms` `email`
`codeDestination`	`string` Masked email address or phone number the confirmation code is sent to.

passwordResetInstructions

{
  "_profile": "https://production.api.apiture.com/schemas/auth/passwordResetInstructions/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "emailAddress": "Casey.Hargrove@example.com",
  "userUri": "https://api.devbank.apiture.com/users/users/7460a72c-a602-464c-894e-9c463a81cc1d",
  "resetPasswordUri": "https://devbank.apiture.com/forgotPassword"
}

Password Reset Instructions (v1.1.0)

Properties used to send the password reset instructions to a user.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`emailAddress`	`string(email)` (required) The user's preferred email address.
`userUri`	`string(uri)` (required) The URI of a user, from the Users API; this identifies the verified user whose password the operator is helping the user reset. `maxLength: 2048`
`resetPasswordUri`	`string(uri)` (required) The URI of the web page where the user can reset their password. `maxLength: 2048`

passwordResetRequest

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

Password Reset Request (v2.0.0)

Create a new password reset.

Properties

Name	Description
`username`	`string(username)` (required) The user's username. `minLength: 2` `maxLength: 64`
`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.

preferredUsername

{
  "_profile": "https://production.api.apiture.com/schemas/auth/preferredUsername/v2.2.0/profile.json",
  "_links": {},
  "username": "john0224",
  "emailAddress": "JohnBankCustomer@example.com",
  "mobilePhone": "+19105550155"
}

Preferred Username (v2.2.0)

A user's requested username, entered when enrolling an existing bank customer user in digital banking. The user can optionally confirm or change their preferred email address and mobile phone number.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`username`	`string(username)` (required) The user's requested username. This must be unique to all current usernames in the system. `minLength: 5` `maxLength: 30`
`emailAddress`	`string(email)` The user's preferred email address. `minLength: 4` `maxLength: 120`
`mobilePhone`	`string` The user's preferred mobile phone number, as a string. The service strips all spaces, hyphens, periods and parentheses from input. The default country code prefix is `+1`. `minLength: 8` `maxLength: 20`

preferredUsernameResponse

{
  "_profile": "https://production.api.apiture.com/schemas/auth/preferredUsernameResponse/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "temporaryPassword": "#pbw+`XNtwPf5,K7"
}

Preferred Username Response (v1.1.0)

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

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`temporaryPassword`	`string` The temporary password created by the service.

root

{
  "_profile": "https://production.api.apiture.com/schemas/common/root/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "id": "apiName",
  "name": "API name",
  "apiVersion": "1.0.0"
}

API Root (v2.1.0)

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

This schema was resolved from common/root.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`_id`	`string` This API's unique ID. `read-only`
`name`	`string` This API's name.
`apiVersion`	`string` This API's version.

simpleLabel

{
  "label": "Board of Directors",
  "description": "string"
}

Simple Label (v1.0.0)

A text label and optional description.

This schema was resolved from common/simpleLabel.

Properties

Name	Description
`label`	`string` (required) A label or title which may be used as labels or other UI controls which present a value.
`description`	`string` A more detailed localized description of a localizable label.

startSessionMfa

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

Start Session MFA (v1.0.0)

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

Properties

Name	Description
`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`.

summaryChallenge

{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractResource/v2.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  }
}

Summary Challenge (v1.1.0)

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

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`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(uri)` 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. `maxLength: 2048`
`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`

tokenRequest

{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json",
  "_links": {}
}

Token Request (v1.0.0)

A request to obtain a secure access token.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`grant_type`	`string` (required) This must be set to one of the following: • `authorization_code` if using the OAuth 2.0 Authorization code flow • `client_credentials` when using client-supplied credentials (key and secret) • `refresh_token` when refreshing an expired or expiring access token. Default: `"authorization_code"` Enumerated values: `authorization_code` `client_credentials` `refresh_token`
`code`	`string` This must be set to the authorization code returned via a callback redirect after calling the `authorize` operation when using the OAuth 2.0 Authorization code flow. This is required if `grant_type` is `authorization_code`.
`redirect_uri`	`string` The callback url for user redirection after successful login and consent with the Apiture Identity Provider. This value must match the value used during the client application registration process and the value passed to `authorize`. Required if using the `authorization_code` flow.
`refresh_token`	`string` The value of the `refresh_token` obtained with the original or expiring/expired access token. Required if `grant_type=refresh_token`.

userConfirmation

{
  "_profile": "https://production.api.apiture.com/schemas/auth/userConfirmation/v2.0.0/profile.json",
  "_links": {},
  "firstName": "John",
  "lastName": "Smith",
  "birthdate": "1975-28-02",
  "taxId": "{encrypted-version-of-users-aaa-bb-cccc-taxId}",
  "captcha": {
    "id": "e44c8ae6-8504-4bb8-bcb3-65066722c2ea",
    "vendor": "google",
    "type": "reCaptcha3"
  },
  "_encryption": {
    "taxId": "sensitive-48729783"
  }
}

User Confirmation Request (v2.0.0)

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

Note that the client must encrypt the sensitive taxId property in the request body using client-side asymmetric encryption. See Encryption for additional details.

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`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(encrypted-tax-id)` (required) Official government identification (tax ID) for this person. The value of `taxId` in requests must be encrypted with the `sensitive` encryption key.
`captcha`	`authenticationCaptcha` (required) The completed client-side CAPTCHA (Completely Automatic Public Turing Test to Tell Computers and Humans Apart) which established the request as a valid interactive request. The service will verify this data to ensure only valid clients call this operation.
`_encryption`	`encryptionMetadata` (required) Metadata about the encrypted `taxId` property.

userConfirmationResponse

{
  "_profile": "https://production.api.apiture.com/schemas/auth/userConfirmationResponse/v1.3.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "queryResult": "matched",
  "challenge": {
    "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
    "_profile": "https://production.api.apiture.com/schemas/auth/challenge/v1.2.0/profile.json",
    "reason": "Transfer amount much higher than normal",
    "contextUri": "https://fi.apiture.com/transfers/scheduledTransfers/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd",
    "minimumAuthenticatorCount": 1,
    "authenticators": {}
  }
}

User Confirmation Response (v1.3.0)

Response from confirming a user within the platform. If the request was well formed, the response contain a Challenge's 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 createUsername 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.

Links

Response and request bodies using this userConfirmationResponse schema may contain the following links:

Rel	Summary	Method
`apiture:createUsername`	Assign a username for a new digital banking platform user	`POST`

Properties

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.

This schema was resolved from common/links.

_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.
read-only

_error error
An object which describes an error. This value is omitted if the operation succeeded without error.
read-only

challenge challenge
A Challenge resource.

queryResult

userConfirmationResult
The result of a request to confirm if a user exists in the online banking system.

userConfirmationResult strings may have one of the following enumerated values:

Value	Description
`unknown`	Unknown: The request did not contain sufficient information to definitively indicate if the user exists or not, _or_ the banking system declines to reveal if the user exists or not.
`matched`	Potentially Matched: A matching user was found in the online banking system. The client should start an authenticator based on the `challenge` response to complete the user confirmation.
`notMatched`	Not Matched: No matching user was found in the online banking system.

These enumeration values are further described by the label group named userConfirmationResult in the response from the getLabels operation.

userConfirmationResult

"unknown"

User Confirmation State (v1.0.0)

The result of a request to confirm if a user exists in the online banking system.

userConfirmationResult strings may have one of the following enumerated values:

Value	Description
`unknown`	Unknown: The request did not contain sufficient information to definitively indicate if the user exists or not, or the banking system declines to reveal if the user exists or not.
`matched`	Potentially Matched: A matching user was found in the online banking system. The client should start an authenticator based on the `challenge` response to complete the user confirmation.
`notMatched`	Not Matched: No matching user was found in the online banking system.

These enumeration values are further described by the label group named userConfirmationResult in the response from the getLabels operation.

Type: string
Enumerated values:
unknown
matched
notMatched

userSession

{
  "_profile": "https://production.api.apiture.com/schemas/auth/userSession/v1.1.0/profile.json",
  "_links": {
    "self": {
      "href": "https://api.devbank.apiture.com/apiName/resourceName/resourceId"
    }
  },
  "_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}

User Session (v1.1.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.

Links

Response and request bodies using this userSession schema may contain the following links:

Rel	Summary	Method
`apiture:continueUserSession`	continueUserSession	`POST`
`apiture:endUserSession`	endUserSession	`POST`

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`_error`	`error` An object which describes an error. This value is omitted if the operation succeeded without error. `read-only`
`_id`	`string` (required) The user session identifier.

userSessionStart

{
  "_profile": "https://production.api.apiture.com/schemas/auth/userSessionStart/v1.0.1/profile.json",
  "_links": {},
  "mfa": {
    "performed": true,
    "tryCount": 1
  }
}

User Session Start (v1.0.1)

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

Properties

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. This schema was resolved from `common/links`.
`_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. `read-only`
`mobileDevice`	`mobileDevice` Information about the mobile device, if the user session is from a native mobile application.
`mfa`	`startSessionMfa` (required) Information related to the multi-factor authentication used to validate the user's login.

usernameRequest

{
  "_profile": "https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json",
  "_links": {},
  "lastName": "Smith",
  "taxId": "1234",
  "birthdate": "1975-02-28"
}

Username request (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

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. This schema was resolved from `common/links`.
`_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. `read-only`
`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.

usernameRequestNotification

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

Username Request (v1.0.0)

Username request resource.

Properties

Name	Description
`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.