How to Manage Gini Accounts

1 Communicating with Gini Pay API via backend/gateway
- 1.1 1. Basic Authentication
- 1.2 2. JWT Authentication (Mutual Authentication)
2 Direct communication between client devices and Gini Pay API
- 2.1 1. Obtain a client token
- 2.2 2. Create a new user
- 2.3 3. Log in as a new user
- 2.4 4. Make API requests with access token

In order to achieve the best results, Gini Pay API should be able to track the requests down to individual users for the following reasons:

Users might have their own opinions about the document type or the correctness of a certain value.
The feedback correctness is decided based on the number of similar values submitted by the users.

Gini offers various ways to perform requests on behalf of individual users without requiring physical interaction. Depending on your use case and your product's architecture, the following API authentication methods are available:

trusted
Your application communicates with Gini Pay API via a common backend that runs on a trusted device. Each request includes the application’s user identifier to specify the user associated with the request. No account management is required.
untrusted
On the first API usage, your application(or Gini Bank SDK) creates an anonymous Gini user in the background and uses the account credentials for subsequent requests. This works best for (mobile) applications where the app communicates directly with Gini Pay API from some untrusted device.

Communicating with Gini Pay API via backend/gateway

There are two types of authentication schemas supported.

1. Basic Authentication

This authentication scheme is based on HTTP Basic Authentication. Your application needs to use HTTP Basic Authentication to authenticate itself with Gini Pay API. Additionally, another header called X-User-Identifier is sent together with the Authorization header in one request. This header is used by the API to identify individual users. Your application is free to choose whatever value it wants for the header, as long as the following constraints are met:

Each user's identifier must be unique.
Once set for a user, the identifier must remain the same.

Keep your client credentials in secret at all times! Otherwise, third parties might get access to sensitive data if they are able to guess how your application generates user identifiers.

This authentication scheme is enabled for your client by Gini. Contact us if you intend to use this feature.

//request the list of user1's documents

curl -v -H 'Accept: application/vnd.gini.v1+json'
    -u 'client-id:client-secret'
    -H 'X-User-Identifier: user1'
    https://pay-api.gini.net/documents

The access token is only needed if it is created by a trusted system (backend or gateway) and used by an untrusted device, for example, a smartphone.

//authenticating on behalf of a derived user
curl -v -X POST -H 'X-User-Identifier: user1'
    -H 'Accept: application/vnd.gini.v1+json'
    -u 'client-id:secret' 'https://pay-api.gini.net/login'
POST https://pay-api.gini.net/login
Authorization: Basic Y2xpZW50LWlkOnNlY3JldA==
Host: pay-api.gini.net
accept: application/vnd.gini.v1+json

//example response

{
  "access_token":"6c470ffa-abf1-41aa-b866-cd3be0ee84f4",
  "token_type":"bearer",
  "expires_in":3599
}

//The returned access token can now be used to make requests to Gini Pay API on behalf of the user. To do so, send the access token as a bearer token in the Authorization request header:

GET /documents HTTP/1.1
Host: pay-api.gini.net
Authorization: BEARER 6c470ffa-abf1-41aa-b866-cd3be0ee84f4
Accept: application/vnd.gini.v1+json
Connection: close

2. JWT Authentication (Mutual Authentication)

This authentication schema is based on Json Web Token’s. In order to authenticate itself with Gini Pay API, your application acts as an identity provider, creates a JWT access token and sends it in the X-JWT-Authorization HTTP header with Bearer prefix along with the actual request. Gini Pay API will then validate this access token to ensure the request is being sent from a trusted source. To enable the validation by Gini Pay API, you need to expose jwk-set endpoint which is accessible from the Gini system.

Sample header of the JWT token should be similar to this:

The signature algorithm should be RS256 to support asymmetric public/private key pairs.

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "iiDnS6hiU60aB5EOPVmBXcG6JhqlzpqvTJARuHnTXeE"
}

The payload of the JWT access token should at least include the following claims:

Claim Name		Description

Claim Name		Description
iss	mandatory	The value holds the issuer of the identity provider.
<user_identifier_claim_name>	mandatory	The value holds a hash which identifies the user, same as `X-User-Identifier` in the basic authentication schema. Claim name is configurable at Gini backend.
<client_id_claim_name>	mandatory	The value holds the client id that communicates with Gini backend, same as `client-id` in the basic authentication schema. Claim name is configurable at Gini backend.
<client_secret_claim_name>	optional	The value holds the client secret that communicates with Gini backend, same as `secret` in the basic authentication schema. The existence of the claim and the claim name is configurable at Gini backend.

Example of JWT claim content with the configuration:

user_identifier_claim_name=x-user-identifier

client_id_claim_name=x-client-id

client_secret_claim_name=x-client-secret

Example of the actual get documents request:

The jwk-set endpoint is used to retrieve the JSON Web Key (JWK) set from the Authorization Server, which contains the cryptographic key(s) used to verify the JSON Web Signature (JWS) of the access token.

Example request to the jwk-set endpoint:

Example response from jwk-set endpoint:

Direct communication between client devices and Gini Pay API

Gini offers the User Center API (UC API) to work with Gini users. Here is a quick step-by-step guide that outlines how to create and use a new anonymous Gini account.

1. Obtain a client token

Before you are able to use the UC API, obtain a client access token. The client access token authorizes your client (that is your application) against the UC API and enables you to create a new user.

You should already have the client ID client-id and the client secret client-secret. They authorize your client (with HTTP Basic Authentication) to obtain the client access token.

See Authenticate Client.

2. Create a new user

Once the client access token is successfully obtained, it's time to create a new user. For that, we require two more values: a username and a password. The username should be represented by a correct email address whose domain part is easily linkable to your application. For example, if your company is called Example Inc. then app.example.org would be a good domain name to use for your application's user accounts.

See Create New User.

3. Log in as a new user

After the new user is created, you can log in. Note that the login request uses HTTP Basic Authentication with the client ID as a username and the client secret as a password. It doesn't require a client access token. The request-response contains an access token that is used to make API requests on behalf of the new user.

See Authenticate on Behalf of User.

4. Make API requests with access token

In order to make API requests, send the access token as a bearer token in the Authorization request header.