Auth v0.16.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.
Discovery
The OpenID Connect Discovery metadata can be retrieved by browsing to the /auth/openid/metadata
URL. The metadata information is public.
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 will provision 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 (OAuth 2.0) Authentication Flows
The Authentication API supports two OpenID Connect authentication flows on top of OAuth 2.0:
- Authorization Code Flow, used with server-side Applications
- Implicit Flow, used with Mobile Applications or Web Applications
More information about using these flows are in the authorize
and getToken
operations below.
OpenID Connect Authorization Code Flow
This interactive flow involves browser redirection to the Apiture Identity Provider URL (the OAuth authorization server) for secure user login and consent. After the first redirection, the user is redirected back to the requesting application using the callback URL that was configured when the application was registered as a consumer.
- Authenticate the user [browser redirection]
- Receive user consent [browser redirection]
- Authenticate the client
- Exchange code for tokens
See Secure Access for further details.
OpenID Connect Implicit Flow
This flow is similar to the code flow but allows clients to retrieve an authentication token directly without the need of an intermediate code. Upon successful authentication, the tokens are returned in the hash fragment of the redirection URL. No refresh tokens are returned using this type of grant.
- Authenticate the user [browser redirection]
- Receive user consent [browser redirection]
See Secure Access for further details.
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 preconfigured 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 will be acknowledged with a 202 status code.
Changing the user's password
To change a user's password, an already authenticated user should [POST
to /my/password
[#op-changeUserPassword). The client should encrypt the old and new password using client side encryption obtained from the [GET /encryptionKeys
]{#op-getEncryptionKeys).
Using the Tokens
Upon successful authentication via the authorize
operation, use the getToken
operation to obtain a oauthToken
response containing an access_token
that can be used to call secured API endpoints. Each request to a secured endpoint must include the access token (also known a bearer token) as part of the Authorization
header: Authorization: Bearer {access_token}
.
The access token has an expiration time in milliseconds in the expires_in
property in the response, and the the refresh token is in the the refresh_token
property. To refresh an expiring or expired access tokenm, use the /oauth2/token#getToken
endpoint with the grant_type
query parameter set to refresh_token
, and the refresh_token
query parameter set to the refresh_token
obtained when the token was first issued.
Devices
For additional security, this API also manages the devices (such as cell phones, tablets, computers) that the user uses for digital banking. This allows the Apiture platform to notify the user if someone logs onto their account from an unknown device. Each device has a unique device ID.
Device management improves the multi-factor authentication (MFA) experience for users. If SMS-based MFA is enabled, end users must input a security code received via SMS in addition to entering their password during every sign-in . With device management, users can specify that a device is trusted and the authentication service will remember the device as trusted. Trusted devices can serve as a second factor of authentication instead of requiring a security code delivered via SMS.
This feature tracks each device/user combination separately, such as a husband and wife logging onto digital banking on a shared laptop or table. If the husband has chosen to trust the device, he may sign in using the device and not have to use secondary authentication such as an code sent via SMS. If the wife has not marked the device as trusted, when they sign in, they will need to use the secondary authentication such as an code sent via SMS.
A financial institution can disable tracking of trusted devices so that other secondary authentication such as SMS codes or biometrics must be used on each sign in.
Identity Challenges
The Challenges and Authenticator operations support additional user identity verification challenges to allow a user to verify they are who they claim to be, such as entering a code send via email or SMS. A challenge represents a resource for tracking this additional authentication.
For example, in the Users API, when a user tries to change their preferred mailing address, email address, or phone number, the operations may require an additional identity verification challenge. This helps prevent fraudulent use if someone gains access to an account and attempts to take it over without the owner's consent or knowledge by changing the account's contact information. Other APIs which may use the Challenge API include the Transfers API to confirm identity before transferring money higher than some user-level transfer threshold or much higher than historical transfers, or the Accounts API when adding or removing joint owners or authorized signers.
API services initiate challenges when required. If an operation requires a challenge, the initial operation fails with a 401 Unauthorized response with an _error
object in the response. That error response has the error type of identityChallengeRequired
. The error object contains a _embedded.challenge
object which describes the challenge (see the challengeErrorResponse
schema).
A challenge consists of:
- 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
, andfailedAt
, andredeemedAt
timestamps.- the
state
of the challenge - other data for limiting and tracking redemption (use) of a challenge
An authenticator contains
- the authentication
type
such assms
oremail
- 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
, andfailedAt
timestampsmaximumRetries
limits how many times an authenticator may be retried
For example, a type
may be sms
which means the authenticator will send an SMS message to the user's mobile device; the message contains a code (4 to 6 digits) which the user must enter in the application. The schema attached to sms
will list the preferred mobile device number(s) for the user or account, and perhaps other allowed mobile device phone numbers. Other types include email
(a similar code is sent to the user at the preferred email address.) Clients must be prepared to handle all the authenticator types.
The client should start the selected authenticators by using a POST
to their apiture:start
links (operation startAuthenticator
. For example, for sms
and email
authenticator types, the service will send a code to the user's preferred mobile phone number or email address respectively. The type
in the authenticator includes a JSON schema which describes the data that should be passed in the authenticator's attributes
. The client should collect data from the user and then post the authenticator resource (with the user data in the attributes
) to the verifyAuthenticator
operation. This validates the data and either completes the authenticator (and challenge) or fails.
After the required authenticators are verified and the challenge has been completed, the client application should retry the initial operation that failed with the 401 error. The client should pass the _id
of the challenge resource in the Apiture-Challenge
request header on this operation retry. Operations which participate in the Challenge protocol will document the optional Apiture-Challenge
request header as one of the operation's parameters.
Challenges and authenticators expire and they are automatically deleted after a delay of several minutes.
Session Tracking
You may use the Authentication API to track user sessions. There are operations to mark the beginning, continuation, and ending of a user session (log on, refresh a user's access token, log off). See the startUserSession
, continueUserSession
, endUserSession
operations.
Error Types
Error responses in this API may have one of the following `type` values.
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.
getTokenAccessDenied
Description: The client is not authorized to generate this token.
Remediation: Make sure the client credentials are valid.
invalidGrant
Description: The provided code is not valid.
Remediation: Check the provided code.
postTokenAccessDenied
Description: The client is not authorized to generate this token.
Remediation: Make sure the client is authorized.
usernameRequestConflict
Description: There was a conflict requesting the username.
Remediation: Make sure the supplied information is correct.
invalidUsernameRequest
Description: The username request was not processed.
Remediation: Check that the user exists and that the attributes match the request.
invalidNewPassword
Description: The new password is not valid.
Remediation: Check that the new password conforms to password policy.
dataNotEncrypted
Description: The data in request was not encrypted or it was encrypted with obsolete keys.
Remediation: Encrypt the data using valid encryption keys.
usernameInUse
Description: The username is already in use.
Remediation: Choose a new username.
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.
accessDenied
Description: The credentials supplied in the request are insufficient to grant access.
Remediation: Check the supplied credentials for validity.
currentPasswordDoesNotMatch
Description: The current password does not match.
Remediation: Check that the current password in the request match the user's current password.
noSuchUser
Description: No users were found for the specified userId.
Remediation: Ensure the supplied userId corresponds to an Apiture user.
challengeNotFound
Description: No Challenge was found for the specified challengeId.
Remediation: Ensure the supplied challengeId corresponds to a valid challenge resource.
authenticatorNotFound
Description: No authenticators were found for the specified authenticatorId and challengeId combination.
Remediation: Ensure the supplied authenticatorId corresponds to a valid authenticator resource.
noSuchDevice
Description: No devices were found for the specified userId.
Remediation: Verify that the device exists for the user and resubmit.
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 | array | undefined |
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 |
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 | array | The list of authenticator types that are in use but missing from the request. Example: `sms,email` |
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.
authenticatorNotCompletable
Description: The authenticator is not in a state that allows completing.
Remediation: Only verify an authenticator if the apiture:verify
link exists.
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.
invalidSession
Description: No session was found.
Remediation: Resubmit request with a valid session.
Download OpenAPI Definition (YAML)
Base URLs:
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 privateclientId
(and optionalclientSecret
) as part of this flow. The client obtains an access token from the server attokenUrl
. It then passes the received access token via theAuthorization: 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 = /auth/oauth2/authorize
- Token URL = /auth/oauth2/token
- OAuth2 client access token authentication. The client authenticates against the server at
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
getMetadata
Code samples
# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/openid/metadata \
-H 'Accept: application/json' \
-H 'API-Key: API_KEY'
GET https://api.devbank.apiture.com/auth/openid/metadata HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/json
var headers = {
'Accept':'application/json',
'API-Key':'API_KEY'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/openid/metadata',
method: 'get',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'API-Key':'API_KEY'
};
fetch('https://api.devbank.apiture.com/auth/openid/metadata',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'API-Key' => 'API_KEY'
}
result = RestClient.get 'https://api.devbank.apiture.com/auth/openid/metadata',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'API-Key': 'API_KEY'
}
r = requests.get('https://api.devbank.apiture.com/auth/openid/metadata', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/openid/metadata");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"API-Key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/openid/metadata", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Returns OpenID Connect Discovery metadata.
GET /openid/metadata
This request returns a JSON structure containing scopes.
Try It
Example responses
200 Response
{}
400 Response
Responses
Status | Description |
---|---|
200 | OK |
The metadata was returned successfully. | |
Schema: authMetadata |
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 will contain 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 will contain details about the request error. | |
Schema: errorResponse |
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
This request redirects the user to the identity provider login page to authenticate the user (securely enter their credentials) and redirect to the application to complete the authorization flow via getToken
.
Parameters
Parameter | Description |
---|---|
response_type (query) |
string Indicates the authentication flow to be used. Use code to specify the usage of the OAuth 2.0 Authorization code flow and token for the OAuth 2.0 implicit grant flow. Default: "code" |
scope (query) |
string This must be set to openid to indicate a request for OpenID authentication and ID token. Default: "openid" |
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. |
state (query) |
string An arbitrary value set by the client to maintain state between the authorization request and the callback. |
redirect_uri (query) |
string (required) The callback url that the user will be redirected to after successful login and consent with the Apiture Identity Provider. This value must match the value used during the client application registration process. The callback url will be called with the authorization code provided as a parameter. Required if using the authorization_code flow. |
Try It
Example responses
400 Response
Responses
Response Headers
Status | Description |
---|---|
302 | Location string |
The login and consent page of the Apiture Identity Provider. |
getToken
Code samples
# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/oauth2/token?grant_type=authorization_code \
-H 'Accept: application/json' \
-H 'Authorization: string' \
-H 'API-Key: API_KEY'
POST https://api.devbank.apiture.com/auth/oauth2/token?grant_type=authorization_code HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/json
Authorization: string
var headers = {
'Accept':'application/json',
'Authorization':'string',
'API-Key':'API_KEY'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/oauth2/token',
method: 'post',
data: '?grant_type=authorization_code',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'Authorization':'string',
'API-Key':'API_KEY'
};
fetch('https://api.devbank.apiture.com/auth/oauth2/token?grant_type=authorization_code',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'string',
'API-Key' => 'API_KEY'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/oauth2/token',
params: {
'grant_type' => 'string'
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'string',
'API-Key': 'API_KEY'
}
r = requests.post('https://api.devbank.apiture.com/auth/oauth2/token', params={
'grant_type': 'authorization_code'
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/oauth2/token?grant_type=authorization_code");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"string"},
"API-Key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/oauth2/token", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Obtain a secure access token.
POST /oauth2/token
Create or refresh an access token for client use. Depending on the value of
the grant_type
query 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.
- To issue the initial token for interactive clients, use
?grant_type=authorization_code
, passing thecode
obtained from theauthorize
operation and theredirect_uri
query parameters. (Both thecode
andredirect_uri
query parameters are required for this grant type.) Clients should save therefresh_token
from the response. - For trusted (non-web, non-mobile) clients, use
?grant_type=client_credentials
and theauthorization
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 originaloauthToken
response from the earlier call to this operation.
All calls require the Authorization
header.
Parameters
Parameter | Description |
---|---|
grant_type (query) |
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 token. Default: "authorization_code" |
code (query) |
string This must be set to the authorization code returned via a callback redirect after calling the authorize operation whenusing the OAuth 2.0 Authorization code flow. This is required if grant_type is authorization_code . |
redirect_uri (query) |
string The callback url that the user will be redirected to after successful login and consent with the Apiture Identity Provider. This value must match the value used during the client application registration process and the value passed to authorize . Required if using the authorization_code flow. |
refresh_token (query) |
string The value of the refresh_token obtained with the original or expiring/expired access token. Required if ?grant_type=refresh_token . |
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. |
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 will contain 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 This error response may have one of the following | |
Schema: errorResponse |
Status | Description |
---|---|
403 | Forbidden |
The client is not authorized to generate a new token. This error response may have one of the following | |
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 will contain details about the request error. | |
Schema: errorResponse |
Response Headers
Status | Description |
---|---|
302 | Location string |
The login and consent page of the Apiture Identity Provider. |
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: */*' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
GET https://api.devbank.apiture.com/auth/encryptionKeys?keys=string 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/encryptionKeys',
method: 'get',
data: '?keys=string',
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/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' => '*/*',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.get 'https://api.devbank.apiture.com/auth/encryptionKeys',
params: {
'keys' => 'array[string]'
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': '*/*',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.get('https://api.devbank.apiture.com/auth/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{"*/*"},
"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/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] (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
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/
) will include a link apiture:getDevices
. This link's href
will resolve the {userId}
for the currently authenticated user.
Parameters
Parameter | Description |
---|---|
userId (path) |
string (required) The user ID of a user. An authenticated user can only view their own devices. |
Try It
Example responses
200 Response
{
"_profile": "https://api.apiture.com/schemas/auth/devices/v1.0.0/profile.json",
"start": 0,
"limit": 100,
"count": 1,
"name": "devices",
"_links": {
"collection": {
"href": "/auth/users/testUser/devices"
}
},
"_embedded": {
"items": [
{
"_profile": "https://api.apiture.com/schemas/auth/device/v1.0.0/profile.json",
"_id": "us-east-1_b6530c4c-572a-403a-9452-cd0c74c715a1",
"name": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
"lastIpAddress": "34.198.94.30",
"trusted": false,
"lastLoggedInAt": "2019-06-25T11:48:18.000Z",
"userId": "testUser"
}
]
}
}
403 Response
Responses
Status | Description |
---|---|
200 | OK |
OK | |
Schema: Inline |
Status | Description |
---|---|
403 | Forbidden |
The client is not authorized to generate a new token. This error response may have one of the following | |
Schema: errorResponse |
Status | Description |
---|---|
404 | Not Found |
The device was not found. The This error response may have one of the following | |
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 will be 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. This error response may have one of the following | |
Schema: errorResponse |
Response Schema
Status Code 200
Property Name | Description |
---|---|
» _links | links An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations. |
»» Link | link Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property. |
»»» href | string(uri) (required) The URI or URI template for the resource/operation this link refers to. |
»»» type | string The media type for the resource. |
»»» templated | boolean If true, the link's href is a URI template. |
»»» title | string An optional human-readable localized title for the link. |
»»» deprecation | string(uri) If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation. |
»»» profile | string(uri) The URI of a profile document, a JSON document which describes the target resource/operation. |
»» _embedded | object Embedded device objects. |
»»» items | [device] An array of devices which user uses to sign in. |
»»»» Device (v1.0.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. |
»»»»» _embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
»»»»» _profile | string(uri) The URI of a resource profile which describes the representation. |
»»»»» _error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
»»»»»» message | string (required) A localized message string describing the error condition. |
»»»»»» _id | string A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. |
»»»»»» statusCode | integer The HTTP status code associate with this error. minimum: 100 maximum: 599 |
»»»»»» type | string An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode . For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet . |
»»»»»» occurredAt | string(date-time) An RFC 3339 UTC time stamp indicating when the error occurred. |
»»»»»» attributes | attributes Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type . |
»»»»»»» Attribute Value | attributeValue The data associated with this attribute. |
»»»»»» remediation | string An optional localized string which provides hints for how the user or client can resolve the error. |
»»»»»» errors | [error] An optional array of nested error objects. This property is not always present. |
»»»»»»» Error | error Describes an error in an API request or in a service called via the API. |
»»»»»»»» message | string (required) A localized message string describing the error condition. |
»»»»»»»» _id | string A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. |
»»»»»»»» statusCode | integer The HTTP status code associate with this error. minimum: 100 maximum: 599 |
»»»»»»»» type | string An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode . For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet . |
»»»»»»»» occurredAt | string(date-time) An RFC 3339 UTC time stamp indicating when the error occurred. |
»»»»»»»» attributes | attributes Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type . |
»»»»»»»»» Attribute Value | attributeValue The data associated with this attribute. |
»»»»»»»» remediation | string An optional localized string which provides hints for how the user or client can resolve the error. |
»»»»»»»» errors | [error] An optional array of nested error objects. This property is not always present. |
»»»»»»»» _links | links An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations. |
»»»»»»» _links | links An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations. |
»»»»»» _id | string The device unique identifier. |
»»»»»» operatingSystem | string The operating system of the device, if known. iOS, Android, macOS, Windows, Linux are examples. An empty or omitted value indicates the value could not be determined. maxLength: 16 |
»»»»»» vendor | string The vendor of the device, if known. Apple, Google, Samsung, LG are examples. An empty or omitted value indicates the value could not be determined. maxLength: 16 |
»»»»»» secondaryId | string An additional unique host-defined device identifier, for example a unique ID for advertising or other purposes. |
»»»»»» name | string The name of the device, derived from the authentication flow. |
»»»»»» type | string The type (category) of the device, if known. 'mobile', 'desktop' are examples. An empty or omitted value indicates the value could not be determined. maxLength: 16 |
»»»»»» lastIpAddress | string The IP address used when the user last logged in with this device. |
»»»»»» trusted | boolean If true , the user indicated that the device is trusted when signing in on the device. Future sign ins on the device will not require alternate multi-factor authentication such as entering a code sent by the financial institution via SMS. If false , the user has not indicated the specific device is trusted. |
»»»»»» lastLoggedInAt | string(date-time) The timestamp of last login. This is in RFC 3339 format, YYYY-MM-DDThh:mm:ss.sssZ |
»»»»»» userId | string The user identified by userId . |
»»»»» _profile | string(uri) The URI of a resource profile which describes the representation. |
»»»»» _error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
»»»»»» message | string (required) A localized message string describing the error condition. |
»»»»»» _id | string A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. |
»»»»»» statusCode | integer The HTTP status code associate with this error. minimum: 100 maximum: 599 |
»»»»»» type | string An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode . For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet . |
»»»»»» occurredAt | string(date-time) An RFC 3339 UTC time stamp indicating when the error occurred. |
»»»»»» attributes | attributes Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type . |
»»»»»»» Attribute Value | attributeValue The data associated with this attribute. |
»»»»»» remediation | string An optional localized string which provides hints for how the user or client can resolve the error. |
»»»»»» errors | [error] An optional array of nested error objects. This property is not always present. |
»»»»»» _links | links An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations. |
»»»»» count | integer The number of items in the collection. This value is optional and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter. |
»»»»» start | integer The start index of this page of items. |
»»»»» limit | integer The maximum number of items per page. |
»»»»» name | string The name of the collection. |
getDevice
Code samples
# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId} \
-H 'Accept: application/json' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
GET https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId} HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/json
var headers = {
'Accept':'application/json',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}',
method: 'get',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.get 'https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.get('https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Return a device for the user
GET /users/{userId}/devices/{deviceId}
Return a specific device for a user. The deviceId
is the unique identifier of a device resource. This operation is typically called via the self
link for an item in the getDevices
collection response.
Parameters
Parameter | Description |
---|---|
userId (path) |
string (required) The user ID of a user. An authenticated user can only view their own devices. |
deviceId (path) |
string (required) The unique identifier of the device. |
Try It
Example responses
200 Response
{
"_profile": "https://api.apiture.com/schemas/auth/device/v1.0.0/profile.json",
"_id": "us-east-1_b6530c4c-572a-403a-9452-cd0c74c715a1",
"name": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
"lastIpAddress": "34.198.94.30",
"trusted": false,
"lastLoggedInAt": "2019-06-25T11:48:18.000Z",
"userId": "testUser"
}
403 Response
Responses
Status | Description |
---|---|
200 | OK |
OK | |
Schema: Inline |
Status | Description |
---|---|
403 | Forbidden |
The client is not authorized to generate a new token. This error response may have one of the following | |
Schema: errorResponse |
Status | Description |
---|---|
404 | Not Found |
The device was not found. The This error response may have one of the following | |
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 will be 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. This error response may have one of the following | |
Schema: errorResponse |
Response Schema
Status Code 200
Property Name | Description |
---|---|
» _links | links An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations. |
»» Link | link Describes a hypermedia link within a _links object in HAL representations. In Apiture APIs, links are HAL links, but Apiture APIs do not use the name or hreflang properties of HAL. Apiture links may include a method property. |
»»» href | string(uri) (required) The URI or URI template for the resource/operation this link refers to. |
»»» type | string The media type for the resource. |
»»» templated | boolean If true, the link's href is a URI template. |
»»» title | string An optional human-readable localized title for the link. |
»»» deprecation | string(uri) If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation. |
»»» profile | string(uri) The URI of a profile document, a JSON document which describes the target resource/operation. |
»» _embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
»» _profile | string(uri) The URI of a resource profile which describes the representation. |
»» _error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
»»» message | string (required) A localized message string describing the error condition. |
»»» _id | string A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. |
»»» statusCode | integer The HTTP status code associate with this error. minimum: 100 maximum: 599 |
»»» type | string An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode . For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet . |
»»» occurredAt | string(date-time) An RFC 3339 UTC time stamp indicating when the error occurred. |
»»» attributes | attributes Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type . |
»»»» Attribute Value | attributeValue The data associated with this attribute. |
»»» remediation | string An optional localized string which provides hints for how the user or client can resolve the error. |
»»» errors | [error] An optional array of nested error objects. This property is not always present. |
»»»» Error | error Describes an error in an API request or in a service called via the API. |
»»»»» message | string (required) A localized message string describing the error condition. |
»»»»» _id | string A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. |
»»»»» statusCode | integer The HTTP status code associate with this error. minimum: 100 maximum: 599 |
»»»»» type | string An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode . For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet . |
»»»»» occurredAt | string(date-time) An RFC 3339 UTC time stamp indicating when the error occurred. |
»»»»» attributes | attributes Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type . |
»»»»»» Attribute Value | attributeValue The data associated with this attribute. |
»»»»» remediation | string An optional localized string which provides hints for how the user or client can resolve the error. |
»»»»» errors | [error] An optional array of nested error objects. This property is not always present. |
»»»»» _links | links An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations. |
»»»» _links | links An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations. |
»»» _id | string The device unique identifier. |
»»» operatingSystem | string The operating system of the device, if known. iOS, Android, macOS, Windows, Linux are examples. An empty or omitted value indicates the value could not be determined. maxLength: 16 |
»»» vendor | string The vendor of the device, if known. Apple, Google, Samsung, LG are examples. An empty or omitted value indicates the value could not be determined. maxLength: 16 |
»»» secondaryId | string An additional unique host-defined device identifier, for example a unique ID for advertising or other purposes. |
»»» name | string The name of the device, derived from the authentication flow. |
»»» type | string The type (category) of the device, if known. 'mobile', 'desktop' are examples. An empty or omitted value indicates the value could not be determined. maxLength: 16 |
»»» lastIpAddress | string The IP address used when the user last logged in with this device. |
»»» trusted | boolean If true , the user indicated that the device is trusted when signing in on the device. Future sign ins on the device will not require alternate multi-factor authentication such as entering a code sent by the financial institution via SMS. If false , the user has not indicated the specific device is trusted. |
»»» lastLoggedInAt | string(date-time) The timestamp of last login. This is in RFC 3339 format, YYYY-MM-DDThh:mm:ss.sssZ |
»»» userId | string The user identified by userId . |
deleteDevice
Code samples
# You can also use wget
curl -X DELETE https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId} \
-H 'Accept: */*' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
DELETE https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId} HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
var headers = {
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}',
method: 'delete',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => '*/*',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.delete 'https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': '*/*',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.delete('https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"*/*"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "https://api.devbank.apiture.com/auth/users/{userId}/devices/{deviceId}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Delete a device registration
DELETE /users/{userId}/devices/{deviceId}
Delete a specific device registration which tracks the use of a device for a user. Once deleted, the user will have to use another secondary authentication method, such as entering a code sent by SMS, when signing in.
Parameters
Parameter | Description |
---|---|
userId (path) |
string (required) The user ID of a user. An authenticated user can only view their own devices. |
deviceId (path) |
string (required) The unique identifier of the device. |
Try It
Example responses
403 Response
Responses
Status | Description |
---|---|
204 | No Content |
No Content. The resource was deleted successfully. |
Status | Description |
---|---|
403 | Forbidden |
The client is not authorized to generate a new token. This error response may have one of the following | |
Schema: errorResponse |
Status | Description |
---|---|
404 | Not Found |
The device was not found. The This error response may have one of the following | |
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 will be 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. This error response may have one of the following | |
Schema: errorResponse |
User Sessions
User Session Life Cycles
startUserSession
Code samples
# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/userSession \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
POST https://api.devbank.apiture.com/auth/userSession HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
var headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/userSession',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"_profile": "https://api.apiture.com/auth/userSessionStart/v1.0.0/model.json",
"mfa": {
"performed": true,
"tryCount": 1
}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/userSession',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => '*/*',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/userSession',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': '*/*',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.post('https://api.devbank.apiture.com/auth/userSession', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/userSession");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"*/*"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/userSession", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
POST /userSession
Start a user's virtual session. Clients should call this to mark when a user
logs in. This operation is not required, but using it allows the
financial institution to monitor and audit users' sessions and help
prevent fraudulent use. The operation returns a session identifer
which the client should pass to continue or complete the session
with the continueUserSession
and endUserSession
operations.
The response contains links to these operations. The response
for this operation is also passed directly to those other operations.
This operation is idempotent. If the session has already been started, this operation returns that session.
Body parameter
{
"_profile": "https://api.apiture.com/auth/userSessionStart/v1.0.0/model.json",
"mfa": {
"performed": true,
"tryCount": 1
}
}
Parameters
Parameter | Description |
---|---|
body (body) |
userSessionStart (required) Client information for tracking the session. |
Try It
Example responses
202 Response
Responses
Status | Description |
---|---|
202 | Accepted |
Accepted | |
Schema: userSession |
Status | Description |
---|---|
400 | Bad Request |
Bad Request. The request body is badly formed or contains invalid data. | |
Schema: #/components/responses/400 |
Status | Description |
---|---|
422 | Unprocessable Entity |
Unprocessable Entity. An aspect of the request was well formed but otherwise invalid. The _error field in the response will contain details about the request error. | |
Schema: #/components/responses/422UserSessionStart |
continueUserSession
Code samples
# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/continuedUserSessions \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
POST https://api.devbank.apiture.com/auth/continuedUserSessions HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
var headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/continuedUserSessions',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"_profile": "https://api.apiture.com/auth/userSession/v1.0.0/model.json",
"_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/continuedUserSessions',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => '*/*',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/continuedUserSessions',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': '*/*',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.post('https://api.devbank.apiture.com/auth/continuedUserSessions', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/continuedUserSessions");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"*/*"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/continuedUserSessions", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
POST /continuedUserSessions
Continue a session. After the client refreshes the user's access token,
it may post the user session to this path to indicate that it wishes to continue
the virtual session, but associated with the new token.
The client must call this operation with the new access token in
the Authorization
header.
This operation is idempotent. If the session has already been continued, this operation returns that session.
Body parameter
{
"_profile": "https://api.apiture.com/auth/userSession/v1.0.0/model.json",
"_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}
Parameters
Parameter | Description |
---|---|
body (body) |
userSession (required) Client information for tracking the continuing user session. This is the userSession returned from either the startUserSession operation or from the most recent call to continueUserSession for this user, whichever was most recent. |
Try It
Example responses
202 Response
Responses
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 is badly formed or contains invalid data. | |
Schema: #/components/responses/400 |
Status | Description |
---|---|
404 | Not Found |
Not Found. The session does not exist. This error may also occur if the session has already been ended. | |
Schema: #/components/responses/404 |
endUserSession
Code samples
# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/completedSessions \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
POST https://api.devbank.apiture.com/auth/completedSessions HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
var headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/completedSessions',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"_profile": "https://api.apiture.com/auth/userSession/v1.0.0/model.json",
"_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/completedSessions',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => '*/*',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/completedSessions',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': '*/*',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.post('https://api.devbank.apiture.com/auth/completedSessions', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/completedSessions");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"*/*"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/completedSessions", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
POST /completedSessions
End a user session. When the client wishes to end a user session, it can call this operation to inform the platform. The client may use an explicit logout operation, or it may end a session after a period of inactivity.
Upon ending a user session, the client should purge any local cached data associated with the user and discard
their access token and the userSession
object.
Body parameter
{
"_profile": "https://api.apiture.com/auth/userSession/v1.0.0/model.json",
"_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}
Parameters
Parameter | Description |
---|---|
body (body) |
userSession (required) Client information for tracking the current user session. This is the userSession returned from either the startSession operation or from the most recent call to continueSession for this user, whichever was most recent. |
Try It
Example responses
400 Response
Responses
Status | Description |
---|---|
204 | No Content |
No Content |
Status | Description |
---|---|
400 | Bad Request |
Bad Request. The request body is badly formed or contains invalid data. | |
Schema: #/components/responses/400 |
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: #/components/responses/404 |
API
The Authentication API
getApi
Code samples
# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/ \
-H 'Accept: application/hal+json'
GET https://api.devbank.apiture.com/auth/ HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/hal+json
var headers = {
'Accept':'application/hal+json'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/',
method: 'get',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'application/hal+json'
};
fetch('https://api.devbank.apiture.com/auth/',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/hal+json'
}
result = RestClient.get 'https://api.devbank.apiture.com/auth/',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/hal+json'
}
r = requests.get('https://api.devbank.apiture.com/auth/', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/hal+json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Top-level resources and operations in this API
GET /
Return links to the top-level resources and operations in this API.
Try It
Example responses
OK
{
"id": "auth",
"name": "Authorization",
"apiVersion": "0.1.0",
"_profile": "https://api.apiture.com/schemas/common/root/v2.0.0/profile.json",
"_links": {
"apiture:authorize": {
"href": "/auth/oauth2/authorize"
},
"apiture:token": {
"href": "/auth/oauth2/token"
},
"apiture:metadata": {
"href": "/auth/openid/metadata"
}
}
}
200 Response
{
"id": "apiName",
"name": "API name",
"apiVersion": "1.0.0",
"_profile": "https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json",
"_links": {}
}
Responses
getApiDoc
Code samples
# You can also use wget
curl -X GET https://api.devbank.apiture.com/auth/apiDoc \
-H 'Accept: application/json'
GET https://api.devbank.apiture.com/auth/apiDoc HTTP/1.1
Host: api.devbank.apiture.com
Accept: application/json
var headers = {
'Accept':'application/json'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/apiDoc',
method: 'get',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json'
};
fetch('https://api.devbank.apiture.com/auth/apiDoc',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json'
}
result = RestClient.get 'https://api.devbank.apiture.com/auth/apiDoc',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json'
}
r = requests.get('https://api.devbank.apiture.com/auth/apiDoc', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/apiDoc");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/apiDoc", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Return API definition document
GET /apiDoc
Return the OpenAPI document that describes this API.
Try It
Example responses
200 Response
{}
Responses
Status | Description |
---|---|
200 | OK |
OK | |
Schema: Inline |
Response Schema
User
usernameRequests
Code samples
# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/usernameRequests \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'API-Key: API_KEY'
POST https://api.devbank.apiture.com/auth/usernameRequests HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: application/json
var headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'API-Key':'API_KEY'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/usernameRequests',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"lastName": "Smith",
"taxId": "1234",
"birthdate": "1975-02-28"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'API-Key':'API_KEY'
};
fetch('https://api.devbank.apiture.com/auth/usernameRequests',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'API-Key' => 'API_KEY'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/usernameRequests',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'API-Key': 'API_KEY'
}
r = requests.post('https://api.devbank.apiture.com/auth/usernameRequests', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/usernameRequests");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"API-Key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/usernameRequests", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Request sending the user an email containing their forgotten username.
POST /usernameRequests
Request sending the user an email containing their forgotten username by submitting the user's key identifying information. (This operation does not create a resource.) An email containing the username is sent to the user as a result of this operation.
Body parameter
{
"lastName": "Smith",
"taxId": "1234",
"birthdate": "1975-02-28"
}
Parameters
Parameter | Description |
---|---|
body (body) |
usernameRequest (required) The data necessary to request the user's username be sent to them. |
Try It
Example responses
202 Response
{
"lastName": "Smith",
"taxId": "1234",
"birthdate": "1975-02-28"
}
422 Response
Responses
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 | |
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 will be blocked from further requests until a period of time has passed. | |
Schema: errorResponse |
confirmUser
Code samples
# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/confirmedUsers \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'API-Key: API_KEY'
POST https://api.devbank.apiture.com/auth/confirmedUsers HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
var headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/confirmedUsers',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"_profile": "https://api.apiture.com/schemas/users/userConfirmation/v1.0.0/model.json",
"firstName": "John",
"lastName": "Smith",
"birthdate": {},
"taxId": "112-22-3333"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY'
};
fetch('https://api.devbank.apiture.com/auth/confirmedUsers',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => '*/*',
'API-Key' => 'API_KEY'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/confirmedUsers',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': '*/*',
'API-Key': 'API_KEY'
}
r = requests.post('https://api.devbank.apiture.com/auth/confirmedUsers', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/confirmedUsers");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"*/*"},
"API-Key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/confirmedUsers", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Convert a user to new digital banking platform
POST /confirmedUsers
After enabling the Apiture platform and importing customers from the banking core, a client application can use this operation to confirm and create a user's login account. The client application should prompt the user for their first and last name, date of birth, and tax identification number (such as a social security number) and submit the data here. A successful operation (the request was well formed) returns a Challenge resource. If this data matches a customer registered in the core, the system will connect the user resource to that customer in the banking core and create a new login account.
The client should then use one of the returned challenge's
authenticators
to verify the user identity. If verified, the user enters their
new username in the client application.
The client should then use the username
operation
to validate and submit the user's new username to create
the user's login account.
This operation returns an error response if the data is not well formed. Since this operation is unauthenticated, the response for a well-formed request does not indicate success or failure. Thus, this operation cannot be used to confirm if a customer exists or not.
Body parameter
{
"_profile": "https://api.apiture.com/schemas/users/userConfirmation/v1.0.0/model.json",
"firstName": "John",
"lastName": "Smith",
"birthdate": {},
"taxId": "112-22-3333"
}
Parameters
Parameter | Description |
---|---|
body (body) |
userConfirmation (required) |
Try It
Example responses
200 Response
Responses
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 will contain 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 will be 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: */*' \
-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: */*
Apiture-Challenge: string
var headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'Apiture-Challenge':'string',
'API-Key':'API_KEY'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/username',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"_profile": "https://api.apiture.com/schemas/auth/credentials/v1.0.1/profie.json",
"username": "john0224"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'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' => '*/*',
'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': '*/*',
'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{"*/*"},
"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 will list any such errors, such as username already in use,
the password does not conform to the password policies, or the Challenge ID
is invalid or expired or has already been redeemed.
If the request is valid, there is no _error
object in the pre-flight validation response.
Validating the request does not count towards the challenge's maximum redemption count.
This operation requires passing a valid Challenge ID in the Apiture-Challenge
request header.
Body parameter
{
"_profile": "https://api.apiture.com/schemas/auth/credentials/v1.0.1/profie.json",
"username": "john0224"
}
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) |
Try It
Example responses
200 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 This error response may have one of the following | |
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 will contain details about the request error. | |
Schema: errorResponse |
Status | Description |
---|---|
409 | Conflict |
Conflict. The username is already in use, or no This error response may have one of the following | |
Schema: errorResponse |
Status | Description |
---|---|
422 | Unprocessable Entity |
Unprocessable Entity. 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 | |
Schema: errorResponse |
createCredentials
Code samples
# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/credentials \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'Apiture-Challenge: string' \
-H 'API-Key: API_KEY'
POST https://api.devbank.apiture.com/auth/credentials HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
Apiture-Challenge: string
var headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'Apiture-Challenge':'string',
'API-Key':'API_KEY'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/credentials',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"_profile": "https://api.apiture.com/schemas/auth/credentials/v1.0.0/profie.json",
"username": "john0224",
"password": "newPassword",
"confirmationCode": "12345"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'Apiture-Challenge':'string',
'API-Key':'API_KEY'
};
fetch('https://api.devbank.apiture.com/auth/credentials',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => '*/*',
'Apiture-Challenge' => 'string',
'API-Key' => 'API_KEY'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/credentials',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': '*/*',
'Apiture-Challenge': 'string',
'API-Key': 'API_KEY'
}
r = requests.post('https://api.devbank.apiture.com/auth/credentials', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/credentials");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"*/*"},
"Apiture-Challenge": []string{"string"},
"API-Key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/credentials", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Create credentials for a new digital banking platform user
POST /credentials
After confirming the user's identity via the confirmUser
operation
and completing the identity verification challenge,
the user can submit their new username and password with this operation.
If there are no errors in the request, the user login account is completed with the requested username and password; the end user may now log in.
This operation also supports pre-flight validation, via the ?preFlightValidate=true
option,
to request that the server validate the credentials.
The _error
object in the 200 OK
response will list any such errors, such as username already in use,
the password does not conform to the password policies, or the Challenge ID
is invalid or expired or has already been redeemed.
If the request is valid, there is no _error
object in the pre-flight validation response.
Validating the request does not count towards the challenge's maximum redemption count.
This operation requires passing a valid Challenge ID in the Apiture-Challenge
request header.
Warning: This operation is deprecated and will be removed in a future release.
Body parameter
{
"_profile": "https://api.apiture.com/schemas/auth/credentials/v1.0.0/profie.json",
"username": "john0224",
"password": "newPassword",
"confirmationCode": "12345"
}
Parameters
Parameter | Description |
---|---|
Apiture-Challenge (header) |
string The unique identifier of a Challenge resource which demonstrates the user has recently verified their identity. See the discussion of Multi-factor authentication challenges above. The value must be the _id string of a valid, redeemable Challenge resource which matches the challenge context. |
preFlightValidate (query) |
boolean If true , the operation performs pre-flight validation of the request body and it does not attempt to create a login account and credentials for the user. |
body (body) |
credentials (required) |
Try It
Example responses
200 Response
Responses
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 This error response may have one of the following | |
Schema: credentialsResponse |
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 will contain details about the request error. | |
Schema: errorResponse |
Status | Description |
---|---|
409 | Conflict |
Conflict. The username is already in use, or no This error response may have one of the following | |
Schema: errorResponse |
Status | Description |
---|---|
422 | Unprocessable Entity |
Unprocessable Entity. 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 | |
Schema: errorResponse |
Password
passwordResetRequest
Code samples
# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/passwordResetRequests \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'API-Key: API_KEY'
POST https://api.devbank.apiture.com/auth/passwordResetRequests HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: application/json
var headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'API-Key':'API_KEY'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/passwordResetRequests',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"username": "john0224",
"taxId": "1234",
"birthdate": "1974-10-27"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'API-Key':'API_KEY'
};
fetch('https://api.devbank.apiture.com/auth/passwordResetRequests',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'API-Key' => 'API_KEY'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/passwordResetRequests',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'API-Key': 'API_KEY'
}
r = requests.post('https://api.devbank.apiture.com/auth/passwordResetRequests', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/passwordResetRequests");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"API-Key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/passwordResetRequests", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Initiate a password reset flow.
POST /passwordResetRequests
Initiate a password reset flow by sending the user's key identifying information. A confirmation code is sent to the user via text message or email as a result of this operation if the information matches. In order to complete the flow, a POST
request to /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 will contain 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 will be 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. This error response may have one of the following | |
Schema: errorResponse |
passwordReset
Code samples
# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/passwordResets \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'API-Key: API_KEY'
POST https://api.devbank.apiture.com/auth/passwordResets HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
var headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/passwordResets',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"_profile": "https://api.apiture.com/schemas/auth/confirmPasswordReset/v1.0.0/profie.json",
"username": "john0224",
"newPassword": "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 will return 202 Accepted if the request is valid.
This operation supports pre-flight validation. If invoked with the preFlightValidate=true
query parameter, the operation validates the confirmationCode
against the generated code, validates the new password to ensure it complies with the financial institution’s password policy, and returns an _error
in the response if there is not a match in the codes or with details of any password policy violations.
Body parameter
{
"_profile": "https://api.apiture.com/schemas/auth/confirmPasswordReset/v1.0.0/profie.json",
"username": "john0224",
"newPassword": "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
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 will contain 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 This error response may have one of the following | |
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 | |
Schema: errorResponse |
changeUserPassword
Code samples
# You can also use wget
curl -X PUT https://api.devbank.apiture.com/auth/my/password \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
PUT https://api.devbank.apiture.com/auth/my/password HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
var headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/my/password',
method: 'put',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"currentPassword": "dhjke45785huryur89rid7liuld8973hdodhwliw474hq4gp47h",
"newPassword": "5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4",
"_encryption": {
"currentPassword": "secret-48729783",
"newPassword": "secret-48729783"
}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/my/password',
{
method: 'PUT',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => '*/*',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.put 'https://api.devbank.apiture.com/auth/my/password',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': '*/*',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.put('https://api.devbank.apiture.com/auth/my/password', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/my/password");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"*/*"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("PUT", "https://api.devbank.apiture.com/auth/my/password", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Change the user password
PUT /my/password
An authenticated user must encrypt (see [GET /encryptionKeys
]{#op-getEncryptionKeys)) and pass currentPassword
and newPassword
in the request body to change its password. This operation requires both apiKey
and accessToken
security.
This operation will return 202 Accepted if the request is valid.
If the request fails, and the user does not know the current password, they can request a password reset by using /passwordResetRequests
.
This operation supports pre-flight validation. If invoked with the preFlightValidate=true
query parameter, the operation only validates the newPassword
against the password policies and returns an _error
in the response with details of any password policy violations.
Body parameter
{
"currentPassword": "dhjke45785huryur89rid7liuld8973hdodhwliw474hq4gp47h",
"newPassword": "5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4",
"_encryption": {
"currentPassword": "secret-48729783",
"newPassword": "secret-48729783"
}
}
Parameters
Parameter | Description |
---|---|
preFlightValidate (query) |
boolean If true , the operation performs pre-flight validation only of the newPassword and it does not attempt to update the user's password. |
body (body) |
passwordChange (required) |
Try It
Example responses
200 Response
Responses
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 will contain 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 This error response may have one of the following | |
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 | |
Schema: errorResponse |
Challenge
redeemChallenge
Code samples
# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/redeemedChallenges?challenge=string \
-H 'Accept: */*' \
-H 'If-Match: string' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
POST https://api.devbank.apiture.com/auth/redeemedChallenges?challenge=string HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
If-Match: string
var headers = {
'Accept':'*/*',
'If-Match':'string',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/redeemedChallenges',
method: 'post',
data: '?challenge=string',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'*/*',
'If-Match':'string',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/redeemedChallenges?challenge=string',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => '*/*',
'If-Match' => 'string',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/redeemedChallenges',
params: {
'challenge' => 'string'
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': '*/*',
'If-Match': 'string',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.post('https://api.devbank.apiture.com/auth/redeemedChallenges', params={
'challenge': 'string'
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/redeemedChallenges?challenge=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"*/*"},
"If-Match": []string{"string"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/redeemedChallenges", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Redeem or use a challenge
POST /redeemedChallenges
When an operation that requires an identity challenge (passed via the Apiture-Challenge
request header), it redeems the challenge to mark it as used. Challenges have a maximum number of times that they may be redeemed. This changes the state
property of the authenticator to redeemed
. This operation is available via the apiture:redeem
link on the challenge resource, if and only if the challenge is eligible for the redeem operation. The response is the updated representation of the challenge.
Parameters
Parameter | Description |
---|---|
challenge (query) |
string (required) A string which uniquely identifies an challenge. This may be the unique _id of the challenge resource or the URI of the challenge. |
If-Match (header) |
string The entity tag that was returned in the ETag response. The If-Match header is optional, but if passed, this must match the current entity tag of the resource. |
Try It
Example responses
200 Response
Responses
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 | |
Schema: errorResponse |
Status | Description |
---|---|
409 | Conflict |
Conflict. The request to redeem the challenged is not allowed. The This error response may have one of the following |
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: */*' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
GET https://api.devbank.apiture.com/auth/challenges HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
var headers = {
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/challenges',
method: 'get',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/challenges',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => '*/*',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.get 'https://api.devbank.apiture.com/auth/challenges',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': '*/*',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.get('https://api.devbank.apiture.com/auth/challenges', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/challenges");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"*/*"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/challenges", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Return a collection of challenges
GET /challenges
Return a paginated sortable filterable searchable collection of challenges. The links in the response include pagination links.
Parameters
Parameter | Description |
---|---|
start (query) |
integer(int64) The zero-based index of the first challenge item to include in this page. The default 0 denotes the beginning of the collection. |
limit (query) |
integer(int32) The maximum number of challenge representations to return in this page. Default: 100 |
sortBy (query) |
string Optional sort criteria. See sort criteria format, such as ?sortBy=field1,-field2 . |
filter (query) |
string Optional filter criteria. See filtering. |
q (query) |
string Optional search string. See searching. |
userId (query) |
string Subset to challenges for the specified user. The value should be the unique {userId} (the _id of a User resource). |
state (query) |
string Subset the challenges to those whose state matches this value. Use | to separate multiple values. For example, ?state=started matches only items whose state is started ; ?state=verified|failed matches items whose state is verified or failed . This is combined with an implicit and with other filters if they are used. See filtering. Enumerated values: pending started verified failed redeemed expired |
Try It
Example responses
200 Response
Responses
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 will contain 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 will contain details about the request error. | |
Schema: errorResponse |
createChallenge
Code samples
# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/challenges \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
POST https://api.devbank.apiture.com/auth/challenges HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
var headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/challenges',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"_links": {
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
},
"_embedded": {},
"_profile": "http://example.com",
"_error": {
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"reason": "string",
"contextUri": "http://example.com",
"userId": "string",
"minimumAuthenticatorCount": 0,
"maximumRedemptionCount": 1,
"code": "stringstringstri"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/challenges',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => '*/*',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/challenges',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': '*/*',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.post('https://api.devbank.apiture.com/auth/challenges', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/challenges");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"*/*"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/challenges", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Create a new challenge
POST /challenges
Create a new challenge. This is called from service code when an operations requires additional user verification. By default, the resulting challenge resource will contain a list of authenticators, one for each authenticator type (see the getAuthenticatorTypes
operation). When creating a challenge, the service can exclude authenticators with either or both ?exclude=
or specify the exact authenticator types to use with ?include=
.
When an operation fails with a 401 due to required authentication response, the services embeds the challenge as the _error._embedded.challenge
object in the response. See also the getAuthenticator
operation and the challenge
and authenticator
schemas for additional details.
A user may have only one active challenge at a time. Creating a new challenge for a user will delete any outstanding challenge resources for that user and any authenticators associated with those challenges. End users cannot call this operation.
Challenges (and their authenticators) expire automatically some time after creation. At a later time, expired, failed, and verified challenges and authenticators are automatically deleted.
Body parameter
{
"_links": {
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
},
"_embedded": {},
"_profile": "http://example.com",
"_error": {
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"reason": "string",
"contextUri": "http://example.com",
"userId": "string",
"minimumAuthenticatorCount": 0,
"maximumRedemptionCount": 1,
"code": "stringstringstri"
}
Parameters
Parameter | Description |
---|---|
include (query) |
string One or more authenticator types or categories which the challenge should exclude from its authenticators. Type names are from the name or category property of the authenticator types resource, such as ?exclude=sms . Multiple types may be specified, separated by commas: ?exclude=sms,biometric . This may be combined with the other filters, but excludes take precedent over ?include . (This notation may be extended in the future to allow additional filter constraints based on authenticator type properties.) |
exclude (query) |
string One or more authenticator types or categories which the challenge should exclude from its authenticators. Type names are from the name or category property of the authenticator types resource, such as ?exclude=sms . Multiple types may be specified, separated by commas: ?exclude=sms,biometric . If both ?include= and ?exclude= are used, the exclusions take precedence inclusions. That is, for ?include=sms&exclude=sms , the sms authenticator will not be used. (This notation may be extended in the future to allow additional filter constraints based on authenticator type properties.) |
body (body) |
createChallenge (required) The data necessary to create a new challenge. |
Try It
Example responses
201 Response
Responses
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 will contain 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 will be 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: */*' \
-H 'If-None-Match: string' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
GET https://api.devbank.apiture.com/auth/challenges/{challengeId} HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
If-None-Match: string
var headers = {
'Accept':'*/*',
'If-None-Match':'string',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/challenges/{challengeId}',
method: 'get',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'*/*',
'If-None-Match':'string',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/challenges/{challengeId}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => '*/*',
'If-None-Match' => 'string',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.get 'https://api.devbank.apiture.com/auth/challenges/{challengeId}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': '*/*',
'If-None-Match': 'string',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.get('https://api.devbank.apiture.com/auth/challenges/{challengeId}', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/challenges/{challengeId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"*/*"},
"If-None-Match": []string{"string"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/challenges/{challengeId}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Fetch a representation of this challenge
GET /challenges/{challengeId}
Return a HAL representation of this challenge resource.
Parameters
Parameter | Description |
---|---|
If-None-Match (header) |
string The entity tag that was returned in the ETag response. If the resource's current entity tag matches, the GET will return 304 (Not Modified) and no response body, else the resource representation will be returned. |
challengeId (path) |
string (required) The unique identifier of this challenge. This is an opaque string. |
Try It
Example responses
200 Response
Responses
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 This error response may have one of the following | |
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. |
Authenticator
retryAuthenticator
Code samples
# You can also use wget
curl -X POST https://api.devbank.apiture.com/auth/retriedAuthenticators?authenticator=string \
-H 'Accept: */*' \
-H 'If-Match: string' \
-H 'API-Key: API_KEY'
POST https://api.devbank.apiture.com/auth/retriedAuthenticators?authenticator=string HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
If-Match: string
var headers = {
'Accept':'*/*',
'If-Match':'string',
'API-Key':'API_KEY'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/retriedAuthenticators',
method: 'post',
data: '?authenticator=string',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'*/*',
'If-Match':'string',
'API-Key':'API_KEY'
};
fetch('https://api.devbank.apiture.com/auth/retriedAuthenticators?authenticator=string',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => '*/*',
'If-Match' => 'string',
'API-Key' => 'API_KEY'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/retriedAuthenticators',
params: {
'authenticator' => 'string'
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': '*/*',
'If-Match': 'string',
'API-Key': 'API_KEY'
}
r = requests.post('https://api.devbank.apiture.com/auth/retriedAuthenticators', params={
'authenticator': 'string'
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/retriedAuthenticators?authenticator=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"*/*"},
"If-Match": []string{"string"},
"API-Key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/retriedAuthenticators", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Retry an authenticator
POST /retriedAuthenticators
Retry or restart an authenticator, for example, if the authentication process failed or if the user never received confirmation. This changes the state
property of the authenticator to started
. This fails operation if the authenticator has been retried more than the allowed number of retries.
This operation is available via the apiture:retry
link on the authenticator resource, if and only if the authenticator is eligible for the retry operation. The response is the updated representation of the authenticator.
Parameters
Parameter | Description |
---|---|
authenticator (query) |
string (required) A string which uniquely identifies an authenticator. This may be the unique _id of the authenticator or the URI of the authenticator. |
If-Match (header) |
string The entity tag that was returned in the ETag response. The If-Match header is optional, but if passed, this must match the current entity tag of the resource. |
Try It
Example responses
200 Response
Responses
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 | |
Schema: errorResponse |
Status | Description |
---|---|
409 | Conflict |
Conflict. The request to retry the authenticator is not allowed. The This error response may have one of the following |
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: */*' \
-H 'If-Match: string' \
-H 'API-Key: API_KEY'
POST https://api.devbank.apiture.com/auth/startedAuthenticators?authenticator=string HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
If-Match: string
var headers = {
'Accept':'*/*',
'If-Match':'string',
'API-Key':'API_KEY'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/startedAuthenticators',
method: 'post',
data: '?authenticator=string',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'*/*',
'If-Match':'string',
'API-Key':'API_KEY'
};
fetch('https://api.devbank.apiture.com/auth/startedAuthenticators?authenticator=string',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => '*/*',
'If-Match' => 'string',
'API-Key' => 'API_KEY'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/startedAuthenticators',
params: {
'authenticator' => 'string'
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': '*/*',
'If-Match': 'string',
'API-Key': 'API_KEY'
}
r = requests.post('https://api.devbank.apiture.com/auth/startedAuthenticators', params={
'authenticator': 'string'
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/startedAuthenticators?authenticator=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"*/*"},
"If-Match": []string{"string"},
"API-Key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/startedAuthenticators", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Start an authenticator
POST /startedAuthenticators
Start a pending
authenticator, initiating the identity verification. For example, starting a sms
or email
authenticator will send a unique code to the user via that channel. This changes the state
property of the authenticator to started
and resets the attributes
data. A started authenticator should be verified via the verifiedAuthenticator
operation. This operation is available via the apiture:start
link on the authenticator resource, if and only if the authenticator is eligible for the start operation. The response is the updated representation of the authenticator.
Parameters
Parameter | Description |
---|---|
authenticator (query) |
string (required) A string which uniquely identifies an authenticator. This may be the unique _id of the authenticator or the URI of the authenticator. |
If-Match (header) |
string The entity tag that was returned in the ETag response. The If-Match header is optional, but if passed, this must match the current entity tag of the resource. |
Try It
Example responses
200 Response
Responses
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 | |
Schema: errorResponse |
Status | Description |
---|---|
409 | Conflict |
Conflict. The request to start the authenticator is not allowed. The This error response may have one of the following | |
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: */*' \
-H 'If-Match: string' \
-H 'API-Key: API_KEY'
POST https://api.devbank.apiture.com/auth/verifiedAuthenticators HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
If-Match: string
var headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'If-Match':'string',
'API-Key':'API_KEY'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/verifiedAuthenticators',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
"_profile": "https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json",
"userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
"state": "started",
"type": {
"name": "sms",
"label": "SMS Code",
"description": "Enter a code sent via SMS to the user's preferred mobile device.",
"category": "device",
"schema": {
"title": "SMS attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via SMS.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
},
"maximumRetries": 3,
"retryCount": 1,
"createdAt": "2019-08-23T12:42:50.375Z",
"expiresAt": "2019-08-23T13:12:50.375Z",
"_links": {
"self": {
"href": "/auth/challenges/2e61e506-1568-4f1a-a93e-4d0a48a06d0e/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
},
"apiture:challenge": {
"href": "/auth/challenges/challenges/b59438cd-5efb-4915-916b-0600bb2a4e1e"
},
"apiture:retry": {
"href": "/auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
},
"apiture:verify": {
"href": "/auth/challenges/verifiedAuthenticators"
}
}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'If-Match':'string',
'API-Key':'API_KEY'
};
fetch('https://api.devbank.apiture.com/auth/verifiedAuthenticators',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => '*/*',
'If-Match' => 'string',
'API-Key' => 'API_KEY'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/verifiedAuthenticators',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': '*/*',
'If-Match': 'string',
'API-Key': 'API_KEY'
}
r = requests.post('https://api.devbank.apiture.com/auth/verifiedAuthenticators', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/verifiedAuthenticators");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"*/*"},
"If-Match": []string{"string"},
"API-Key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/verifiedAuthenticators", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Verify a user's identity
POST /verifiedAuthenticators
Complete the verification of a user's identity by POST
ing the authenticator to this path, passing the authentication data in the authenticator's attributes
. For example, to verify an sms
or email
authenticator, the client should send the code that was sent to the user via SMS or email in attributes.code
. If the authentication data is valid, this changes the state
property of the authenticator to verified
. In addition, if all the challenges' authenticators have been verified successfully, the challenge is also marked as verified
. If the attributes
data are invalid, the authenticator is marked failed
. Failed authenticators may be retried (restarted) via the retryAuthenticator
operation.
This operation is available via the apiture:verify
link on the authenticator resource, if and only if the authenticator is eligible for the apiture:verify
operation. The authenticator must have been started (see the startAuthenticator
operation and the apiture:start
link) before being verified. The response is the updated representation of the authenticator.
Body parameter
{
"_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
"_profile": "https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json",
"userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
"state": "started",
"type": {
"name": "sms",
"label": "SMS Code",
"description": "Enter a code sent via SMS to the user's preferred mobile device.",
"category": "device",
"schema": {
"title": "SMS attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via SMS.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
},
"maximumRetries": 3,
"retryCount": 1,
"createdAt": "2019-08-23T12:42:50.375Z",
"expiresAt": "2019-08-23T13:12:50.375Z",
"_links": {
"self": {
"href": "/auth/challenges/2e61e506-1568-4f1a-a93e-4d0a48a06d0e/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
},
"apiture:challenge": {
"href": "/auth/challenges/challenges/b59438cd-5efb-4915-916b-0600bb2a4e1e"
},
"apiture:retry": {
"href": "/auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
},
"apiture:verify": {
"href": "/auth/challenges/verifiedAuthenticators"
}
}
}
Parameters
Parameter | Description |
---|---|
If-Match (header) |
string The entity tag that was returned in the ETag response. The If-Match header is optional, but if passed, this must match the current entity tag of the resource. |
body (body) |
authenticator (required) The body is the authenticator object, with the attributes set as per the authenticator type. |
Try It
Example responses
200 Response
Responses
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 | |
Schema: errorResponse |
Status | Description |
---|---|
409 | Conflict |
Conflict. The request to verify the authenticator is not allowed. The This error response may have one of the following | |
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: */*' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
POST https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
var headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"_links": {
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
},
"_embedded": {},
"_profile": "http://example.com",
"_error": {
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"type": {
"name": "sms",
"label": "SMS code",
"description": "Enter a code sent via SMS to the user's preferred mobile device.",
"category": "device",
"schema": {
"title": "SMS attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via SMS.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
},
"maximumRetries": 0
}';
const headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => '*/*',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.post 'https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': '*/*',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.post('https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"*/*"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Create a new authenticator
POST /challenges/{challengeId}/authenticators
Create a new authenticator. This is only called during the creation of a new challenge resource, from the createChallenge
operation. End users cannot call this operation.
Body parameter
{
"_links": {
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
},
"_embedded": {},
"_profile": "http://example.com",
"_error": {
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"type": {
"name": "sms",
"label": "SMS code",
"description": "Enter a code sent via SMS to the user's preferred mobile device.",
"category": "device",
"schema": {
"title": "SMS attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via SMS.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
},
"maximumRetries": 0
}
Parameters
Parameter | Description |
---|---|
body (body) |
createAuthenticator (required) The data necessary to create a new authenticator. |
challengeId (path) |
string (required) The unique identifier of this challenge. This is an opaque string. |
Try It
Example responses
201 Response
Responses
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 | |
Schema: errorResponse |
Status | Description |
---|---|
404 | Not Found |
Not Found. There is no such challenge resource at the specified This error response may have one of the following | |
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: */*' \
-H 'If-None-Match: string' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
GET https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId} HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
If-None-Match: string
var headers = {
'Accept':'*/*',
'If-None-Match':'string',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}',
method: 'get',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'*/*',
'If-None-Match':'string',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => '*/*',
'If-None-Match' => 'string',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.get 'https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': '*/*',
'If-None-Match': 'string',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.get('https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"*/*"},
"If-None-Match": []string{"string"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/challenges/{challengeId}/authenticators/{authenticatorId}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Fetch a representation of this authenticator
GET /challenges/{challengeId}/authenticators/{authenticatorId}
Return a HAL representation of this authenticator resource. This GET
operation is available via the self
link of the authenticators inside a challenge resource.
Parameters
Parameter | Description |
---|---|
If-None-Match (header) |
string The entity tag that was returned in the ETag response. If the resource's current entity tag matches, the GET will return 304 (Not Modified) and no response body, else the resource representation will be returned. |
challengeId (path) |
string (required) The unique identifier of this challenge. This is an opaque string. |
authenticatorId (path) |
string (required) The unique identifier of this authenticator. This is an opaque string. |
Try It
Example responses
200 Response
Responses
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 This error response may have one of the following | |
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: */*' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
GET https://api.devbank.apiture.com/auth/authenticatorTypes HTTP/1.1
Host: api.devbank.apiture.com
Accept: */*
var headers = {
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/authenticatorTypes',
method: 'get',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const headers = {
'Accept':'*/*',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/authenticatorTypes',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => '*/*',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.get 'https://api.devbank.apiture.com/auth/authenticatorTypes',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': '*/*',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.get('https://api.devbank.apiture.com/auth/authenticatorTypes', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/authenticatorTypes");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"*/*"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.devbank.apiture.com/auth/authenticatorTypes", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Retrieve the set of authenticator types
GET /authenticatorTypes
Return the set of reserved authenticator type names. The type
property of a authenticator must be one of these values. This set may be updated by the financial institution via the updateAuthenticatorTypes
operation. The default list includes the following types:
sms
email
Try It
Example responses
200 Response
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: */*' \
-H 'If-Match: string' \
-H 'API-Key: API_KEY' \
-H 'Authorization: Bearer {access-token}'
PUT https://api.devbank.apiture.com/auth/authenticatorTypes HTTP/1.1
Host: api.devbank.apiture.com
Content-Type: application/json
Accept: */*
If-Match: string
var headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'If-Match':'string',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.devbank.apiture.com/auth/authenticatorTypes',
method: 'put',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"sms": {
"name": "sms",
"label": "SMS code",
"description": "Enter a code sent via SMS to the user's preferred mobile device.",
"category": "device",
"schema": {
"title": "SMS attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via SMS.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
},
"email": {
"name": "email",
"label": "Email code",
"description": "Enter a code sent via email to the user's preferred email address.",
"category": "device",
"schema": {
"title": "Email attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `email`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's preferred email address. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via email.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'*/*',
'If-Match':'string',
'API-Key':'API_KEY',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.devbank.apiture.com/auth/authenticatorTypes',
{
method: 'PUT',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => '*/*',
'If-Match' => 'string',
'API-Key' => 'API_KEY',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.put 'https://api.devbank.apiture.com/auth/authenticatorTypes',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': '*/*',
'If-Match': 'string',
'API-Key': 'API_KEY',
'Authorization': 'Bearer {access-token}'
}
r = requests.put('https://api.devbank.apiture.com/auth/authenticatorTypes', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.devbank.apiture.com/auth/authenticatorTypes");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"*/*"},
"If-Match": []string{"string"},
"API-Key": []string{"API_KEY"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("PUT", "https://api.devbank.apiture.com/auth/authenticatorTypes", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Replace the set of authenticator types
PUT /authenticatorTypes
A financial institution can use this operation to register additional types of authenticators that they may issue to their users when a service needs to issue an identify verification challenge to the user. The type
property of an authenticator must be one of these reserved names. This operation completely replaces the set of reserved authenticator type names, so it should include all items from the getAuthenticatorTypes
that are in use. This operation is only available to financial institution administrators.
Body parameter
{
"sms": {
"name": "sms",
"label": "SMS code",
"description": "Enter a code sent via SMS to the user's preferred mobile device.",
"category": "device",
"schema": {
"title": "SMS attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via SMS.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
},
"email": {
"name": "email",
"label": "Email code",
"description": "Enter a code sent via email to the user's preferred email address.",
"category": "device",
"schema": {
"title": "Email attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `email`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's preferred email address. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via email.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
}
}
Parameters
Parameter | Description |
---|---|
If-Match (header) |
string The entity tag that was returned in the ETag response. The If-Match header is optional, but if passed, this must match the current entity tag of the resource. |
body (body) |
authenticatorTypes (required) The set of authenticator types. |
Try It
Example responses
200 Response
Responses
Status | Description |
---|---|
200 | OK |
OK | |
Schema: authenticatorTypes |
Status | Description |
---|---|
400 | Bad Request |
Bad Request. The request body is badly formed or contains invalid data. | |
Schema: #/components/responses/400 |
Status | Description |
---|---|
409 | Conflict |
Conflict. The request attempts to remove a type that is in use in existing authenticator resources. | |
Schema: #/components/responses/409AuthenticatorTypesConflict |
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. |
Schemas
usernameRequest
{
"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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
lastName | string (required) The user's last name(case sensitive). |
taxId | string (required) Last 4 digits of the user tax ID. minLength: 4
maxLength: 4
|
birthdate | string(date) (required) The user's birth date in RFC 3339 YYYY-MM-DD date format.
|
passwordResetRequest
{
"username": "john0224",
"taxId": "1234",
"birthdate": "1974-10-27"
}
Password Reset Request (v1.0.0)
Create a new password reset.
Properties
Name | Description |
---|---|
username | string (required) The user's username. |
taxId | string (required) Last 4 digits of the user tax ID. minLength: 4
maxLength: 4
|
birthdate | string(date) (required) The user's birth date in RFC 3339 YYYY-MM-DD date format.
|
passwordReset
{
"codeDeliveryMethod": "email",
"codeDestination": "b***@m***.com"
}
Password Reset (v1.0.0)
Password reset resource.
Properties
Name | Description |
---|---|
codeDeliveryMethod | string Confirmation code delivery method.
|
codeDestination | string Masked email address or phone number the confirmation code is sent to. |
usernameRequestNotification
{
"lastName": "Smith",
"taxId": "1234",
"birthdate": "1975-02-28"
}
Username Request (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.
|
authMetadata
{}
Authentication metadata (v1.0.0)
A map of (name, value) pairs which describe then the OpenID Provider metadata.
Properties
oauthToken
{
"access_token": "string",
"token_type": "string",
"expires_in": 0,
"refresh_token": "string"
}
OAuth Tokens (v1.0.0)
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: from this response: |
token_type | string The form of token returned. This is typically the string Bearer and is the key which subsequent calls should use (along with the access_token above) in the Authorization header when making authenticated API requests.
|
expires_in | integer(int64) The number of seconds until the access_token expires. When it expires, use the refresh_token to request a new access token.
|
refresh_token | string A token to use when the access_token expires. The client should retain this securely so it can obtain a new access_token later when the access token expires.
|
attributes
{
"property1": {},
"property2": {}
}
Attributes
An optional map of name/value pairs which contains additional dynamic data about the resource.
Properties
Name | Description |
---|---|
additionalProperties | attributeValue The data associated with this attribute. |
passwordChange
{
"currentPassword": "dhjke45785huryur89rid7liuld8973hdodhwliw474hq4gp47h",
"newPassword": "5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4",
"_encryption": {
"currentPassword": "secret-48729783",
"newPassword": "secret-48729783"
}
}
Password change (v1.0.0)
Representation used to change a user password. The request must contain the currentPassword
, the newPassword
. The client encrypts these values using the secret
encryption key and store the corresponding encryption key aliases in the _encryption
metadata property.
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.
|
_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. |
currentPassword | string(encrypted-password) 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) 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 Metadata about the encrypted currentPassword and newPassword properties.
|
confirmPasswordReset
{
"_profile": "https://api.apiture.com/schemas/auth/confirmPasswordReset/v1.0.0/profie.json",
"username": "john0224",
"newPassword": "5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4",
"confirmationCode": "12345",
"_encryption": {
"newPassword": "secret-48729783"
}
}
Confirm Password Reset (v1.0.0)
Representation used to confirm a password reset flow.
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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
newPassword | string(encrypted-password) 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 A confirmation code send when the user initiated password reset. |
username | string The username. |
_encryption | encryptionMetadata Metadata about the encrypted newPassword property.
|
preferredUsername
{
"_profile": "https://api.apiture.com/schemas/auth/credentials/v1.0.1/profie.json",
"username": "john0224"
}
Preferred Username (v1.0.1)
A new user's requested username.
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.
|
_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. |
username | string The user's requested username. |
preferredUsernameResponse
{
"_profile": "https://api.apiture.com/schemas/auth/credentials/v1.0.0/profie.json",
"temporaryPassword": "#pbw+`XNtwPf5,K7"
}
Preferred Username Response (v1.0.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.
|
_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. |
temporaryPassword | string The temporary password created by the service. |
credentials
{
"_profile": "https://api.apiture.com/schemas/auth/credentials/v1.0.0/profie.json",
"username": "john0224",
"password": "newPassword",
"confirmationCode": "12345"
}
New user credentials (v1.0.0)
A new user's requested username and password.
Warning: The schema credentials
is deprecated. The schema credentials
was deprecated on version v0.13.2
of the API. credentials
will be removed on version v1.0.0
of the API.
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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
password | string(encrypted-password) A new user's password. |
username | string The user's requested username. |
credentialsResponse
{
"_links": {
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
},
"_embedded": {},
"_profile": "http://example.com",
"_error": {
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
}
}
Credentials Response (v1.0.0)
Response from submitting new username and password 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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
device
{
"_profile": "https://api.apiture.com/schemas/auth/device/v1.0.0/profile.json",
"_id": "us-east-1_b6530c4c-572a-403a-9452-cd0c74c715a1",
"name": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
"lastIpAddress": "34.198.94.30",
"trusted": false,
"lastLoggedInAt": "2019-06-25T11:48:18.000Z",
"userId": "testUser"
}
Device (v1.0.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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
_id | string The device unique identifier. read-only
|
operatingSystem | string The operating system of the device, if known. iOS, Android, macOS, Windows, Linux are examples. An empty or omitted value indicates the value could not be determined. read-only
maxLength: 16
|
vendor | string The vendor of the device, if known. Apple, Google, Samsung, LG are examples. An empty or omitted value indicates the value could not be determined. read-only
maxLength: 16
|
secondaryId | string An additional unique host-defined device identifier, for example a unique ID for advertising or other purposes. |
name | string The name of the device, derived from the authentication flow. read-only
|
type | string The type (category) of the device, if known. 'mobile', 'desktop' are examples. An empty or omitted value indicates the value could not be determined. read-only
maxLength: 16
|
lastIpAddress | string The IP address used when the user last logged in with this device. |
trusted | boolean If true , the user indicated that the device is trusted when signing in on the device. Future sign ins on the device will not require alternate multi-factor authentication such as entering a code sent by the financial institution via SMS. If false , the user has not indicated the specific device is trusted.
|
lastLoggedInAt | string(date-time) The timestamp of last login. This is in RFC 3339 format, YYYY-MM-DDThh:mm:ss.sssZ
|
userId | string The user identified by userId .
|
devices
{
"_profile": "https://api.apiture.com/schemas/auth/devices/v1.0.0/profile.json",
"start": 0,
"limit": 100,
"count": 1,
"name": "devices",
"_links": {
"collection": {
"href": "/auth/users/testUser/devices"
}
},
"_embedded": {
"items": [
{
"_profile": "https://api.apiture.com/schemas/auth/device/v1.0.0/profile.json",
"_id": "us-east-1_b6530c4c-572a-403a-9452-cd0c74c715a1",
"name": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
"lastIpAddress": "34.198.94.30",
"trusted": false,
"lastLoggedInAt": "2019-06-25T11:48:18.000Z",
"userId": "testUser"
}
]
}
}
Devices (v1.0.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.
|
_embedded | object Embedded device objects. |
» items | [device] An array of devices which user uses to sign in. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
count | integer The number of items in the collection. This value is optional and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter. |
start | integer The start index of this page of items. |
limit | integer The maximum number of items per page. |
name | string The name of the collection. |
createAuthenticator
{
"_links": {
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
},
"_embedded": {},
"_profile": "http://example.com",
"_error": {
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"type": {
"name": "sms",
"label": "SMS code",
"description": "Enter a code sent via SMS to the user's preferred mobile device.",
"category": "device",
"schema": {
"title": "SMS attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via SMS.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
},
"maximumRetries": 0
}
Create Authenticator (v1.0.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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
type | authenticatorType (required) The type of this authenticator. This must be one of the items in the /authenticatorTypes resource.
|
maximumRetries | integer The maximum number of times the user may retry this authenticator. If 0 , the user must authenticate correctly on the first try. When an authenticator is retried, the client should POST to the apiture:retry link on the authenticators; absence of the link means the user cannot retry the authenticator. The default is 3 .
maximum: 10
|
authenticator
{
"_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
"_profile": "https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json",
"userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
"state": "started",
"type": {
"name": "sms",
"label": "SMS Code",
"description": "Enter a code sent via SMS to the user's preferred mobile device.",
"category": "device",
"schema": {
"title": "SMS attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via SMS.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
},
"maximumRetries": 3,
"retryCount": 1,
"createdAt": "2019-08-23T12:42:50.375Z",
"expiresAt": "2019-08-23T13:12:50.375Z",
"_links": {
"self": {
"href": "/auth/challenges/2e61e506-1568-4f1a-a93e-4d0a48a06d0e/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
},
"apiture:challenge": {
"href": "/auth/challenges/challenges/b59438cd-5efb-4915-916b-0600bb2a4e1e"
},
"apiture:retry": {
"href": "/auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
},
"apiture:verify": {
"href": "/auth/challenges/verifiedAuthenticators"
}
}
}
Authenticator (v1.0.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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
type | authenticatorType The type of this authenticator. This must be one of the items in the /authenticatorTypes resource.
|
maximumRetries | integer The maximum number of times the user may retry this authenticator. If 0 , the user must authenticate correctly on the first try. When an authenticator is retried, the client should POST to the apiture:retry link on the authenticators; absence of the link means the user cannot retry the authenticator. The default is 3 .
maximum: 10
|
_id | string The unique identifier for this authenticator resource. This is an immutable opaque string assigned upon creation. read-only
|
userId | string The user ID of the user who is requested to verify their identity. |
state | authenticatorState The state of this authenticator. This is derived and read-only. read-only
|
retryCount | integer The actual number of times a user has retried this authenticator. read-only
maximum: 10
|
attributes | object Data collected from the user that is used to verify this authenticator. This data conforms to the schema defined in the type . For example, for sms , the attributes must contains a code .
|
createdAt | string(date-time) The time stamp when authenticator was created, in RFC 3339 UTC date-time format ( YYYY-MM-DDThh:mm:ss.sssZ ).
read-only
|
verifiedAt | string(date-time) The time stamp when authenticator was verified in RFC 3339 UTC date-time format ( YYYY-MM-DDThh:mm:ss.sssZ ).
read-only
|
failedAt | string(date-time) The time stamp when the user failed to verify their identity verification (authentication) for this challenge, in RFC 3339 UTC date-time format ( YYYY-MM-DDThh:mm:ss.sssZ ).
read-only
|
expiresAt | string(date-time) The time stamp when the this challenge expires, in RFC 3339 UTC date-time format ( YYYY-MM-DDThh:mm:ss.sssZ ).
read-only
|
createChallenge
{
"_links": {
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
},
"_embedded": {},
"_profile": "http://example.com",
"_error": {
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"reason": "string",
"contextUri": "http://example.com",
"userId": "string",
"minimumAuthenticatorCount": 0,
"maximumRedemptionCount": 1,
"code": "stringstringstri"
}
Create Challenge (v1.0.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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
reason | string (required) The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or informational purposes. |
contextUri | string(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
|
summaryChallenge
{
"_links": {
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
},
"_embedded": {},
"_profile": "http://example.com",
"_error": {
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"reason": "string",
"contextUri": "http://example.com",
"userId": "string",
"minimumAuthenticatorCount": 0,
"maximumRedemptionCount": 1,
"_id": "string",
"redemptionCount": 0,
"state": "pending",
"createdAt": "2020-05-21T14:05:09Z"
}
Summary Challenge (v1.0.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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
reason | string The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or informational purposes. |
contextUri | string(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
|
challenge
{
"_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
"_profile": "https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json",
"reason": "Transfer amount much higher than normal",
"contextUri": "https://fi.apiture.com/users/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd/addresses/ha1",
"minimumAuthenticatorCount": 1,
"authenticators": [
{
"_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
"_profile": "https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json",
"userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
"state": "started",
"type": {
"name": "sms",
"label": "SMS Code",
"description": "Enter a code sent via SMS to the user's preferred mobile device.",
"category": "device",
"schema": {
"title": "SMS attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via SMS.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
},
"maximumRetries": 3,
"retryCount": 1,
"createdAt": "2019-08-23T12:42:50.375Z",
"expiresAt": "2019-08-23T13:12:50.375Z",
"_links": {
"self": {
"href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
},
"apiture:challenge": {
"href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c"
},
"apiture:retry": {
"href": "/auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
},
"apiture:verify": {
"href": "/auth/challenges/verifiedAuthenticators"
}
}
}
],
"maximumRedemptionCount": 1,
"redemptionCount": 0,
"state": "pending",
"createdAt": "2019-08-23T11:37:55.375Z",
"expiresAt": "2019-08-23T12:37:55.375Z",
"_links": {
"self": {
"href": "/auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a"
},
"apiture:redeem": {
"href": "/auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a"
}
}
}
Challenge (v1.0.0)
A resource which represents an identity verification challenge to a user. The user must verify one or more of the authentication methods defined in this challenge in order to proceed with a banking operation (such as scheduling a larger than normal transfer, adding a joint owner or authorized signer to an account, or changing their mailing address or mobile phone number).
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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
reason | string The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or informational purposes. |
contextUri | string(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
|
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.
Type: string
Enumerated values: pending
started
verified
failed
redeemed
expired
authenticatorState
"pending"
Authenticator State (v1.0.0)
The state of a challenge authenticator resource.
- The
startAuthenticator
operation (linkapiture:start
) changes the state frompending
tostarted
. - The
retryAuthenticator
operation (linkapiture:retry
) changes the state tostarted
and is only allowed if the authenticator has more retries available. - The
verifyAuthenticator
operation (linkapiture:verify
) validates theattributes
and changes the state toverified
if valid or tofailed
if invalid.
Type: string
Enumerated values: pending
started
verified
failed
expired
challenges
{
"_profile": "https://api.apiture.com/schemas/challenges/challenges/v1.0.0/profile.json",
"start": 10,
"limit": 10,
"count": 67,
"name": "challenges",
"_links": {
"self": {
"href": "/auth/challenges?start=10&limit=10"
},
"first": {
"href": "/auth/challenges?start=0&limit=10"
},
"next": {
"href": "/auth/challenges?start=20&limit=10"
},
"collection": {
"href": "/auth/challenges"
}
},
"_embedded": {
"items": [
{
"_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
"_profile": "https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json",
"_links": {
"self": {
"href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c"
}
}
},
{
"_id": "d62c0701-0d74-4836-83f9-ebf3709442ea",
"_profile": "https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json",
"_links": {
"self": {
"href": "/auth/challenges/d62c0701-0d74-4836-83f9-ebf3709442ea"
}
}
}
]
}
}
Challenge Collection (v1.0.0)
Collection of challenges. The items in the collection are ordered in the _embedded.items
array; the name
is challenges
. The top-level _links
object may contain pagination links (self
, next
, prev
, first
, last
, collection
.)
Properties
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.
|
_embedded | object Embedded objects. |
» items | [summaryChallenge] An array containing a page of challenge items. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
count | integer The number of items in the collection. This value is optional and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter. |
start | integer The start index of this page of items. |
limit | integer The maximum number of items per page. |
name | string The name of the collection. |
authenticatorCategory
"knowledge"
authenticatorCategory (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.
Type: string
Enumerated values: knowledge
biometric
device
authenticatorTypes
{
"sms": {
"name": "sms",
"label": "SMS code",
"description": "Enter a code sent via SMS to the user's preferred mobile device.",
"category": "device",
"schema": {
"title": "SMS attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via SMS.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
},
"email": {
"name": "email",
"label": "Email code",
"description": "Enter a code sent via email to the user's preferred email address.",
"category": "device",
"schema": {
"title": "Email attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `email`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's preferred email address. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via email.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
}
}
Authenticator types (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. |
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.
|
challengeErrorResponse
{
"_links": {
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
},
"_embedded": {},
"_profile": "http://example.com",
"_error": {
"message": "string",
"_id": "string",
"statusCode": 422,
"type": "string",
"occurredAt": "2018-02-02T03:37:15.375Z",
"attributes": {
"property1": {},
"property2": {}
},
"remediation": "string",
"errors": [
{
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
}
],
"_links": {
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
},
"_embedded": {
"challenge": {
"_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
"_profile": "https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json",
"reason": "Transfer amount much higher than normal",
"contextUri": "https://fi.apiture.com/users/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd/addresses/ha1",
"minimumAuthenticatorCount": 1,
"authenticators": [
{
"_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
"_profile": "https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json",
"userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
"state": "started",
"type": {
"name": "sms",
"label": "SMS Code",
"description": "Enter a code sent via SMS to the user's preferred mobile device.",
"category": "device",
"schema": {
"title": "SMS attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via SMS.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
},
"maximumRetries": 3,
"retryCount": 1,
"createdAt": "2019-08-23T12:42:50.375Z",
"expiresAt": "2019-08-23T13:12:50.375Z",
"_links": {
"self": {
"href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
},
"apiture:challenge": {
"href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c"
},
"apiture:retry": {
"href": "/auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
},
"apiture:verify": {
"href": "/auth/challenges/verifiedAuthenticators"
}
}
}
],
"maximumRedemptionCount": 1,
"redemptionCount": 0,
"state": "pending",
"createdAt": "2019-08-23T11:37:55.375Z",
"expiresAt": "2019-08-23T12:37:55.375Z",
"_links": {
"self": {
"href": "/auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a"
},
"apiture:redeem": {
"href": "/auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a"
}
}
}
}
}
}
Challenge Error Response (v1.0.0)
When an operation requires an additional identity verification challenge, it returns a 401 Unauthorized response status code and an error response with a challenge resource embedded in the _error._embedded.challenge
. This informs the caller that they should verify the challenge via one or more of its authenticators
, then retry the operation with the Apiture-Challenge
header that references the challenge's _id
.
Properties
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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | challengeError The description of the error. |
challengeError
{
"message": "string",
"_id": "string",
"statusCode": 422,
"type": "string",
"occurredAt": "2018-02-02T03:37:15.375Z",
"attributes": {
"property1": {},
"property2": {}
},
"remediation": "string",
"errors": [
{
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
}
],
"_links": {
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
},
"_embedded": {
"challenge": {
"_id": "0399abed-fd3d-4830-a88b-30f38b8a365c",
"_profile": "https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json",
"reason": "Transfer amount much higher than normal",
"contextUri": "https://fi.apiture.com/users/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd/addresses/ha1",
"minimumAuthenticatorCount": 1,
"authenticators": [
{
"_id": "7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3",
"_profile": "https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json",
"userId": "b2720469-3497-4b82-8b85-30f2155aa66d",
"state": "started",
"type": {
"name": "sms",
"label": "SMS Code",
"description": "Enter a code sent via SMS to the user's preferred mobile device.",
"category": "device",
"schema": {
"title": "SMS attributes",
"description": "Schema for an authenticator's `attributes` when the authenticator type is `sms`.",
"type": "object",
"required": [
"code",
"length"
],
"properties": {
"code": {
"type": "string",
"description": "A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'.",
"minLength": 3,
"maxLength": 10
},
"length": {
"description": "The number of digits/characters that are sent to the user via SMS.",
"type": "integer",
"minimum": 3,
"maximum": 10,
"example": 6
}
}
}
},
"maximumRetries": 3,
"retryCount": 1,
"createdAt": "2019-08-23T12:42:50.375Z",
"expiresAt": "2019-08-23T13:12:50.375Z",
"_links": {
"self": {
"href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
},
"apiture:challenge": {
"href": "/auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c"
},
"apiture:retry": {
"href": "/auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3"
},
"apiture:verify": {
"href": "/auth/challenges/verifiedAuthenticators"
}
}
}
],
"maximumRedemptionCount": 1,
"redemptionCount": 0,
"state": "pending",
"createdAt": "2019-08-23T11:37:55.375Z",
"expiresAt": "2019-08-23T12:37:55.375Z",
"_links": {
"self": {
"href": "/auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a"
},
"apiture:redeem": {
"href": "/auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a"
}
}
}
}
}
Challenge Error (v1.0.0)
The operation error description with an embedded identity challenge.
Properties
Name | Description |
---|---|
message | string A localized message string describing the error condition. |
_id | string A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. read-only
|
statusCode | integer The HTTP status code associate with this error. minimum: 100
maximum: 599
|
type | string An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the statusCode . For example, instead of just 400 Bad Request, the type may be much more specific. such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet .
|
occurredAt | string(date-time) An RFC 3339 UTC time stamp indicating when the error occurred. |
attributes | attributes Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the minimum and maximum values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error type .
|
remediation | string An optional localized string which provides hints for how the user or client can resolve the error. |
errors | [error] An optional array of nested error objects. This property is not always present. |
_links | links An optional map of links, mapping each link relation to a link object. This model defines the _links object of HAL representations.
|
_embedded | object Embedded objects |
» challenge | challenge The details of the identity verification challenge. |
userConfirmation
{
"_profile": "https://api.apiture.com/schemas/users/userConfirmation/v1.0.0/model.json",
"firstName": "John",
"lastName": "Smith",
"birthdate": {},
"taxId": "112-22-3333"
}
User Confirmation Request (v1.0.0)
User data which confirms a customer has a banking account at the financial institution. The service does not persist this data.
Properties
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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
firstName | string (required) The person's first name (or given name). |
lastName | string (required) The person's last name (or surname). |
birthdate | string(date) (required) The contact's birth date in YYYY-MM-DD format.
|
taxId | string (required) Official government identification (tax ID) for this person. maxLength: 16
|
userConfirmationResponse
{
"_profile": "https://api.apiture.com/schemas/users/userConfirmationResponse/v1.0.0/model.json"
}
User Confirmation Response (v1.0.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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
challenge | challenge A Challenge resource. |
userSessionStart
{
"_profile": "https://api.apiture.com/auth/userSessionStart/v1.0.0/model.json",
"mfa": {
"performed": true,
"tryCount": 1
}
}
User Session Start (v1.0.0)
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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
mobileDevice | mobileDevice Information about the mobile device, if the user session is from a native mobile application. |
mfa | startSessionMfa Information related to the multi-factor authentication used to validate the user's login. |
startSessionMfa
{
"performed": true,
"tryCount": 1
}
Start Session MFA (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 .
|
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 |
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
|
userSession
{
"_profile": "https://api.apiture.com/auth/userSession/v1.0.0/model.json",
"_id": "f2059c7a-bd6f-48d8-bb10-513e575a40a7"
}
User Session (v1.0.0)
A user session. This representation contains links to continued the user session (POST
) or end this user session (POST
); the request and response body for both is a `userSession' object.
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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
_id | string The user session identifier. |
encryptionKeys
{
"_profile": "https://production.api.apiture.com/schemas/common/encryptionKeys/v1.0.0/model.json",
"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
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.
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.
|
_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. |
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. |
root
{
"id": "apiName",
"name": "API name",
"apiVersion": "1.0.0",
"_profile": "https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json",
"_links": {}
}
API Root
A HAL response, with hypermedia _links
for the top-level resources and operations in API.
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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
_id | string This API's unique ID. read-only
|
name | string This API's name. |
apiVersion | string This API's version. |
errorResponse
{
"_profile": "https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json",
"_error": {
"_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
"message": "The value for deposit must be greater than 0.",
"statusCode": 422,
"type": "positiveNumberRequired",
"attributes": {
"value": -125.5
},
"remediation": "Provide a value which is greater than 0",
"occurredAt": "2018-01-25T05:50:52.375Z",
"_links": {
"describedby": {
"href": "https://api.apiture.com/errors/positiveNumberRequired"
}
},
"_embedded": {
"errors": []
}
}
}
Error Response
Describes an error response, typically returned on 4xx or 5xx errors from API operations. The _error
object contains the error 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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
abstractRequest
{
"_profile": "{uri of resource profile.json}",
"_links": {
"self": {
"href": "{uri of current resource}"
}
}
}
Abstract Request
An abstract schema used to define other request-only schemas. This is a HAL resource representation, minus the _error
defined in 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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
abstractResource
{
"_profile": "{uri of resource profile.json}",
"_links": {
"self": {
"href": "{uri of current resource}"
}
}
}
Abstract Resource
An abstract schema used to define other schemas for request and response bodies. This is a HAL resource representation. This model contains hypermedia _links
, and either optional domain object data with _profile
and optional _embedded
objects, or an _error
object. In responses, if the operation was successful, this object will not include the _error
, but if the operation was a 4xx or 5xx error, this object will not include _embedded
or any data fields, only _error
and optionally _links
.
Properties
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.
|
_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. |
encryptionMetadata
{}
Enryption Metadata
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
→ string
. The keys are names of the encrypted property; each value is the alias
of the rotating public encryption key that the client used to encrypt the named property. For example, for the original request body payload below, the client encrypts the password
properties with the secret
key and the hint
properties with the sensitive
key.
{
"old" : {
"password": "noise-tube-branch-4183",
"hint": "bang nano twig ext",
"effectiveAt" : "2020-01-09T050:00.00Z"
},
"new" : {
"password": "mile-leave-began-9315",
"hint": "1600 take-your ",
"effectiveAt" : "2020-03-09T08:00:00.000Z"
},
"reason" : "I forgot my password"
}
At the time of the encryption, the secret
key has the alias secret-48729783
and the sensitive
key has the alias sensitive-47839398
, so the _encryption
metadata shows those aliases for the password
and hint
properties. Other data is not encrypted.
{
"old": {
"password": "E389478492",
"hint": "E487903092478",
"effectiveAt" : "2020-01-09T050:00.00Z",
"_encryption": {
"password" : "secret-48729783",
"hint" : "sensitive-47839398"
}
},
"new": {
"password": "E320480203",
"hint": "E489229004",
"effectiveAt" : "2020-03-09T08:00:00.000Z"
"_encryption": {
"password" : "secret-48729783",
"hint" : "sensitive-47839398"
}
"reason" : "I forgot my password"
}
For brevity, the encrypted data is represented as "Ennnn"
but in reality, encrypted data will be longer ASCII data.
Properties
collection
{
"_links": {
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
},
"_embedded": {},
"_profile": "http://example.com",
"_error": {
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
},
"count": 0,
"start": 0,
"limit": 0,
"name": "string"
}
Collection
A collection of resources. This is an abstract model schema which is extended to define specific resource collections.
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.
|
_embedded | object An optional map of nested resources, mapping each nested resource name to a nested resource representation. |
_profile | string(uri) The URI of a resource profile which describes the representation. |
_error | error An object which describes an error. This value is omitted if the operation succeeded without error. |
count | integer The number of items in the collection. This value is optional and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter. |
start | integer The start index of this page of items. |
limit | integer The maximum number of items per page. |
name | string The name of the collection. |
error
{
"_id": "2eae46e1575c0a7b0115a4b3",
"message": "Descriptive error message...",
"statusCode": 422,
"type": "errorType1",
"remediation": "Remediation string...",
"occurredAt": "2018-01-25T05:50:52.375Z",
"errors": [
{
"_id": "ccdbe2c5c938a230667b3827",
"message": "An optional embedded error"
},
{
"_id": "dbe9088dcfe2460f229338a3",
"message": "Another optional embedded error"
}
],
"_links": {
"describedby": {
"href": "https://developer.apiture.com/errors/errorType1"
}
}
}
Error
Describes an error in an API request or in a service called via the API.
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.
|
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
A rotating public encryption key.
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 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 or proxy for the actual rotating key. Keys rotate every few minutes. The alias identifies a specific active public/private key pair. This alias should be used 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. |
links
{
"property1": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
},
"property2": {
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
}
Links
An optional map of links, mapping each link relation to a link object. This model defines the _links
object of HAL representations.
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.
|
link
{
"href": "/contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f",
"title": "Applicant"
}
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.
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. |
attributeValue
{}
Attribute Value
The data associated with this attribute.
Properties
encryptionKeyName
"secret"
Encryption Key Name
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 chosen by the client when requesting encryption keys.