APIs
This document describes how to register an application as an IBM Food Trust (IFT) System User, and configure the application to submit credentials and upload data (assets and certificates) to the IFT solution.
The IBM Food Trust (IFT) APIs enable authenticated (and authorized) end users, including system users and applications, to upload data to the IFT solution network. To successfully upload GS1 Asset XML and Certificate JSON to the IFT solution, authenticated users must submit their credentials with each API call. Once the submitted data is validated and transformed by the solution, the assets and certificates are created on the network and available for transactions with other authorized users.
The diagram shown below (Figure 1.) illustrates the overall flow of creating an application System ID and submitting data to IFT through API calls:
Figure 1. IFT system user authentication and API calls
The three steps shown above in Figure 1. are described in detail below:
- To call an IFT API, the application (system user) must have a registered System ID. An Organization Administrator must create the System ID using the Manage Users Dashboard, and manually record the generated System ID, Client ID, and secret (password) for the application. These credentials must then be stored in a form that is consumable by the application—as a configuration file or environment variables, for example.
- The application submits its System ID, Client ID and Secret in a call to the Authorization API Access Token endpoint. If successful, the API returns an access token (JSON Web Token/JWT) to the application.
- The application submits its received access token (JWT) in a call to the IFT API Post Asset or Post Certificate endpoint, to upload assets or certificates to IFT. Information about the created asset or certificate is returned to the application.
The Authorization API returns an access token (JWT) to a registered and authenticated user, which must be specified when uploading data (assets and certificates) to the IBM Food Trust (IFT) solution.
A GET call to the Access Token endpoint returns a JSON Web Token (JWT), as defined in RFC 7519, to an authenticated caller. The authenticated user or application then specifies the access token, in the Authorization header of an API request, to submit data to the IFT solution.
Notes:
- JWT access tokens expire after three hours, but can be renewed prior to expiration. If expired, the IFT API returns a 401 message (User Unauthorized).
- A Java library is provided to obtain an access token without calling the GET Access Token endpoint directly. See How do I obtain an authorization token? for more information.
| Host name |
|---|
| https://fs-identity.mybluemix.net/ |
| HTTP Method | Endpoint | Purpose |
|---|---|---|
| POST | /identity/v0/token |
Obtain an access token (JWT) |
| Header Parameter | Value |
|---|---|
| Content-Type | application/json |
| Accept | application/json |
The parameters shown below are specified in a call to the Access Token endpoint, as JSON data in the payload. The values are then defined and displayed in the organization's IFT Manage Users Dashboard, as follows:
| Property Name | Type | Description |
|---|---|---|
| username | string | System ID is displayed in Manage Users Dashboard. |
| password | string | Secret is displayed in Manage Users Dashboard. |
| grant_type | string | Grant type (only password is supported) |
| client_id | string | Client ID is displayed in Manage Users Dashboard. |
One of three responses is typically returned by the Access Token endpoint:
| Response | Meaning |
|---|---|
| 200 | Access token created |
| 400 | Error in parameters |
| 401 | User Unauthorized |
A successful call to the Access Token endpoint returns the following JSON data:
| Property Name | Description |
|---|---|
| id_token | Access token (JWT) |
| success | Response code (200) |
- 401: User Unauthorized. A 401 response indicates a problem with the credentials (username/password/client_id) submitted to the endpoint. Ensure that the correct credentials for the System ID, created using the Manage Users Dashboard, were submitted.
- 400: Bad Data. A 400 response indicates a problem with the uploaded data. The response includes a detailed description of the problem.
For additional error messages, refer to IFT Solution Errors.
Attention: For compliance with data privacy laws, no data that personally identifies an individual should be submitted to the IBM Food Trust solution.
Call the Asset endpoint to submit an XML message to the IFT solution in the required message format. For help generating XML messages in the correct format, the XML Generator and Excel Converter tools are available.
The IFT API endpoints are documented in Swagger:
| HTTP Method | Endpoint | Purpose |
|---|---|---|
| POST | /fs/connector/v1/assets |
Submits XML to Food Trust solution. |
For authentication, the caller's access token JWT must be submitted in the Authorization header of the POST request:
| Header Parameter | Value |
|---|---|
| Authorization |
Bearer + ' ' (a space character) + Access Token (JWT)
|
One of three responses is typically returned by this endpoint:
| Response | Meaning |
|---|---|
| 201 | Asset Created |
| 400 | Error in XML |
| 401 | User Unauthorized |
- 401: User Unauthorized. A 401 response indicates a problem with the credentials (username/password/client_id) submitted to the endpoint. Ensure that the correct credentials for a System ID, created using the Manage Users Dashboard, are submitted.
- 400: Bad Data. A 400 response indicates a problem with the uploaded data. The response includes a detailed description of the problem.
For additional error messages, refer to IFT Solution Errors.
Call the Certificate endpoint to send certificate JSON to the IFT solution in the required message format
| HTTP Verb | Endpoint | Purpose |
|---|---|---|
| POST | /fs/connector/v1/assets/certificates |
Sends certificate JSON to IFT |
| Header Parameter | Value |
|---|---|
| Authorization | Bearer (token) |
One of three responses is typically returned by the Certificate endpoint:
| Response | Meaning |
|---|---|
| 201 | Asset Created |
| 400 | Error in JSON |
| 401 | User Unauthorized |
- 401: User Unauthorized. A 401 response indicates a problem with the credentials (username/password/client_id) submitted to the endpoint. Ensure that the correct credentials for a System ID, created using the Manage Users Dashboard, were submitted.
- 400: Bad Data. A 400 response indicates a problem with the uploaded data. The response includes a detailed description of the problem.
For additional error messages, refer to IFT Solution Errors.