Introduction to API TKEY7
The TKEY7 APIs are built on well-known REST principles and have predictable behavior. The API supports DELETE, POST, and GET requests. The API always returns a JSON-formatted response, regardless of the type of request.
The API uses HTTP as the primary protocol and is suitable for development in any programming language that can work with HTTP libraries.
| Parameters | Description |
|---|---|
| header | Parameters are passed in the HTTP request header. |
| body | Parameters are passed in the request body. |
| path | Parameters are passed as part of the path in the URL. They are highlighted with curly braces—{}. |
| query | Parameters are passed as URL request parameters. Are they specified after the ?. |
TKEY7 processes the received request immediately and returns the processing result. The response contains the HTTP response code, standard headers, and, if necessary, the response body.
The main entity of API TKEY7 is an object. Each request is associated with performing a specific action on the object, for example, creating or deleting an object and obtaining information about it.
When a request is successfully processed, TKEY7 returns the created, modified, or requested object in the response body or a list of objects. The parameters of the response body depend on the request.
If something is wrong with the request, then for HTTP response codes: 400, 401, 403, 404, 406, 409, and 500, the response body will be returned in JSON format with an error description.
| Name | Type | Description | Required |
|---|---|---|---|
| build_version | string | Service build version. | No |
| code | string | Error code. | No |
| endpoint_url | string | URL of the endpoint that failed with an error. | No |
| long_message | string | Detailed error description. | Yes |
| member_identification | string | Member Identifier. Example: bankName. | No |
| service_name | string | Service name. | No |
| short_message | string | Short error description. | Yes |
| timestamp | number (int64) | Event timestamp. Example: 1651224866578. | Yes |
| troubleshooting_id | string | Identifier indicating the error source. | No |
Authentication
One must use an OAuth token and pass it with each request to authenticate requests.
curl https://us.bankname.payments.tkey7.com/client/v1/api/digital-accounts \-H "Authorization: Bearer <OAuth-token>"
To use TKEY7 features, a User must request permission to receive an OAuth token from a User-Member with Administrator Access Rights.
The User-Member creates API access tokens with Administrator Access Rights in the Web Office interface.
Get an Access Token
Step 1. Log in to the Web Office
A User-Member with Administrator Access Rights must log in to the client portal.
Step 2. Create a User
User-Member with Administrator Access Rights should go to the “User Management” section and create a new User with the Access Rights Viewer or Manager.
Step 3. Create a JWT OAuth token
User-Member with Administrator Access Rights should go to “Access Token Management” and create a new OAuth token for a User with the Access Rights of a Viewer or Manager.
To create a JWT must specify the following parameters:
- Member Identifier in TKEY7 if the organization has multiple Deployed Member Nodes.
- Digital Account Identifiers for which access will be allowed.
- Allowed IP addresses from which the User can make requests.
- Permitted Endpoints to which the User will be allowed access.
The Access Token session is 24 hours, so the User-Member with Administrator Access Rights must create a new Access Token.
A User-Member with Viewer or Manager Access Rights must update the Access Token every fifteen minutes or sooner by calling /oauth-token/refresh endpoint; otherwise, the Token is automatically revoked.