Skip to main content

Configuring a Wallet

The Wallet Admin API is used to administer the application's database. The majority of the functionality configures FPX ecosystem metadata and should align with values defined at the Authorization Server (e.g. AS_BASE_URL/registry/resource/resource_definition/)

Prerequisites and Assumptions​

This section of the guide is meant for the people who will be operating and administering the Wallet Server. It assumes the reader is familiar with the FPX solution and its components. The Wallet is a core component in FPX and therefore its configuration requires comprehension of most FPX concepts such as OAuth (authorization, resources and scopes), and the various ecosystems roles (Identity Provider, Resource Server, Authorization Server, and Client Service Provider)

To use the Wallet Admin API:

  1. The Wallet database must be accessible.
    • The Wallet server should have been run at least once to initialize the database.
  2. The Wallet Admin API server must be accessible at some WS_ADMIN_URI.
    • The server should have access to the application database (1).
  3. The administrator must have an appropriate authorization token.
  4. The request must include the desired API version in a ApiVersion header. The default is v1.0.
  5. The request should include an Accept-Language header. See the Supporting Features section below.
  6. The request should include a Content-Type header with a value of application/vnd.api+json.

How to define and use the Authorization Token​

All Admin API endpoints require the use of the Authorization HTTP header. The Wallet Admin API currently uses a static access token to authorize all requests.

The value of the Authorization Token can be defined in application config section of the Helm chart, using the property wallet-admin.staticToken. The value of this token will be represented in the following pages as {{WS_ADMIN_STATIC_TOKEN}}.

Environment variables​

For a given FPX deployment, there will be a number of values that are common across components and across API calls. The API calls shown in the following sections represent these values as variables surround by two pairs of curly braces. These variables should be defined beforehand and recorded for easy reference as you go through this guide.

The variables are as follows:

  • {{WS_ADMIN_STATIC_TOKEN}} - as explained above
  • {{WS_ADMIN_URI}} - this is the URI of the Wallet Admin API, and should match the host name of the Wallet Admin API defined in the Wallet Helm chart, but with “/json-api” appended
  • {{AUTH_SERVER_URI}} - this is the URI of the Authorization Server, and should match the host name of the Authorization Server in its respective Helm chart

Testing a Successful Configuration​

When using the Wallet Admin API, there are a few ways to check if the attempted operation was successful:

  • A 2XX http response. All APIs return a 2XX type http status code on success. The response body should be checked against the openapi specification.
  • The object being administered is updated in the Wallet Application server API. (WALLET_SERVER/registry/**)
  • If the application server is not running, this can also be verified by inspecting the appropriate table in the application database.
  • Test the front-end application. If successfully configured, the front-end client should be able to see and interact with the configured partner (e.g. connect to a new data source).

Wallet API - Supporting Features​

Localization​

The Wallet Admin API includes localization support, and it is recommended to configure a new deployment with localization support from the beginning unless you know that you won't need it. For that reason, this guide includes the Accept-Language header in all API requests where it is appropriate to include it. The language value set in that header is English, so be sure to change that in the sample API requests if you know you want to configure a different language, to begin with.

The localization feature is covered in more detail here.

Registry API​

The Wallet Server (not Wallet Admin API) exposes a registry API based on the current DB state. This Registry API can be found in this openapi document.

OpenAPI Spec​

The API described below has a companion openapi specification. This YAML file is best viewed using a tool such as http://editor.swagger.io/.

JSON-API Spec​

The Wallet Admin API makes use of a framework called Elide, specifically its implementation of the JSON-API specification. The format of the API calls shown in this guide is representative of this specification. While it can be verbose, it also provides many useful features. For further information, see the following links: