How to Manage Gini Accounts

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 identifies the user the request is made for via the application's user identifier. 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 those account credentials for subsequent requests. This works best for (mobile) applications where the app communicates directly with Gini Pay API on an 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. Your application acts as an identity provider and creates JWT access token and send it in X-JWT-Authorization http header with Bearer prefix along with an actual request to authenticate itself with Gini Pay API. Gini Pay API will then validate this access token to ensure the request is being sent from the trusted source. To enable 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
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.

Sample 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

{
  ...
  "exp": 2025803444,
  "iss": "http://issuer-url-of-your-identity-provider",
  "typ": "Bearer",
  "x-user-identifier": "user1",
  "x-client-secret": "clientId",
  "x-client-id": "<clientSecret>",
  ...
}

Finally sample actual get documents request:

//request the list of user1's documents
curl -v -H 'Accept: application/vnd.gini.v1+json'
    -H 'X-JWT-Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJpaURuUzZoaVU2MGFCNUVPUFZtQlhjRzZKaHFsenBxdlRKQVJ1SG5UWGVFIn0.eyJleHAiOjIwMjgwMjUzOTEsImlhdCI6MTcxMjY2NTM5MSwianRpIjoiN2RmZTVkYzYtMWIyYi00MzdhLWE2MTAtOWZmYWMwMGFlMTk1IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MTgwL3JlYWxtcy9TcHJpbmdCb290S2V5Y2xvYWsiLCJzdWIiOiJkZDJiYjg3Mi1iMTc2LTRkNjktYTcyOC1lMTMzNzRkOWJhNDYiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJsb2dpbi1hcHAiLCJzZXNzaW9uX3N0YXRlIjoiMjgxOTE5NDItYzc5ZS00ZTI0LTk5ODktNDQ4YjkzNWFjMmE2IiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwODEiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbInVzZXIiXX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCBtaWNyb3Byb2ZpbGUtand0Iiwic2lkIjoiMjgxOTE5NDItYzc5ZS00ZTI0LTk5ODktNDQ4YjkzNWFjMmE2IiwieC11c2VyLWlkZW50aWZpZXIiOiJ1c2VyMSIsInVwbiI6InVzZXIxIiwieC1jbGllbnQtc2VjcmV0IjoiY2xpZW50U2VjcmV0IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsIngtY2xpZW50LWlkIjoiY2xpZW50SWQiLCJuYW1lIjoiQmFuayBVc2VyIEZpcnN0IE5hbWUgQmFuayBVc2VyIExhc3QgTmFtZSIsImdyb3VwcyI6WyJ1c2VyIl0sInByZWZlcnJlZF91c2VybmFtZSI6InVzZXIxIiwiZ2l2ZW5fbmFtZSI6IkJhbmsgVXNlciBGaXJzdCBOYW1lIiwiZmFtaWx5X25hbWUiOiJCYW5rIFVzZXIgTGFzdCBOYW1lIiwiZW1haWwiOiJsb2NhbC1hZG1pbkBtYWlsLmNvbSJ9.MOOsftcPMA55aOGh9FwVXvW8Q-HfgFA9l7K9IaJJQQBkBkp4DfkO5ad9P17UWqhiLL20vjCVLP2Dv_fIx0lQQg2SZBBvKvyrssfI7XRTN4_aYVW-5-TVPGQiy_b-1iAQhZ9L6wGSlKUbrw5P_QockvkvqSlYs_LhMH7Rg6xjFVRMGzbAiQIY_8NpL5cRB8AxKJpepWKju4wnmeseoj9rnVqFfLodd7k6BYkTs52qcQj3d-6aZVeyGoEOU0xtFgGOUpwI_r_bh4EDq8zoTIsHwM5kx3AJL_BatdkQw5vj10GDtfmgd-oO2ABJHMnh15OawO9xRk5zY2kDcDM4R1LNOA'
    https://pay-api.gini.net/documents

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.

Sample request to the jwk-set endpoint:

curl --location "http://<your-identity-provider-jwk-set-url>"

Sample response from jwk-set endpoint:

{
    "keys": [
        {
            "kid": "iiDnS6hiU60aB5EOPVmBXcG6JhqlzpqvTJARuHnTXeE",
            "kty": "RSA",
            "alg": "RS256",
            "use": "sig",
            "n": "ojHl0zZHpPCHCzRoJSXkGF4afKsAFul5ZYTz-xuAJcE8udTtbSh5TtRC_5LpWgB-Pp26KWGLQ0Hy-mYJ5i-hGk9d33p_GfQVu3o86ANeUN-QbOzsCZEH6ACAkfa7Q7SgNDT_Ane-BVxYYcviuDjGOxqoy1FJNMoHCuy8SffEET3z-wBEkUV_7jN70G0VARH5TzHaX27UAt5HAwZyN2Hgrb94mBPZmLLF04s-atY52bzHLLe-0j6QKBfqG0jr2aMsXjjuRLDDY8dc2gqD9KjthuQXNBaQS_xD9lczHGBeCHfVy3swIe2dkW5dJeK4J5kMgEvGxaFCgQ7V8_NMxJbS2Q",
            "e": "AQAB",
            "x5c": [
                "MIICszCCAZsCBgGOws+hxjANBgkqhkiG9w0BAQsFADAdMRswGQYDVQQDDBJTcHJpbmdCb290S2V5Y2xvYWswHhcNMjQwNDA5MTIyMTExWhcNMzQwNDA5MTIyMjUxWjAdMRswGQYDVQQDDBJTcHJpbmdCb290S2V5Y2xvYWswggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCiMeXTNkek8IcLNGglJeQYXhp8qwAW6XllhPP7G4AlwTy51O1tKHlO1EL/kulaAH4+nbopYYtDQfL6ZgnmL6EaT13fen8Z9BW7ejzoA15Q35Bs7OwJkQfoAICR9rtDtKA0NP8Cd74FXFhhy+K4OMY7GqjLUUk0ygcK7LxJ98QRPfP7AESRRX/uM3vQbRUBEflPMdpfbtQC3kcDBnI3YeCtv3iYE9mYssXTiz5q1jnZvMcst77SPpAoF+obSOvZoyxeOO5EsMNjx1zaCoP0qO2G5Bc0FpBL/EP2VzMcYF4Id9XLezAh7Z2Rbl0l4rgnmQyAS8bFoUKBDtXz80zEltLZAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAJglhNvRvEyKJZuuueYbZOSvTzw9vKUOxt9p2ZOPX7IAic9zdz+zG6FAHbbz5u+GcATJvvQqsGTdc9FpMhBjvR7nknd9y5pXtD9h3T01kImi5Ux+KDEnrr3Luki7LrG9SQUIU8UwqdoWrTNLyTzr1rLL4hv90Nrwi+17Q2Zvy9el5ulwkUyHrhuy/7WioPLQyyFtzYpLfWCQ3z+HPzL5N8fehhNNhXU+giU3Dd7c7yZ9Yz1/ikwGYJ7CnFpm+MraoSO6HAQQD0ZPFJI0z0G1RXwDB1wIFfHOUZQ1KURArS7555q5ecUCAHBh6ynephljCKL6xMMjsViP+bvdY+uV3AE="
            ],
            "x5t": "UL5gdQ7qSgT2XqVBPNPvOk1tSXI",
            "x5t#S256": "aIPyqcbR6vbdn2Su3DhDT8LlzIUG39nv6qPzm5wnmUo"
        }
    ]
}

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 the example on the right.

See Authenticate Client.

//obtain the client token

curl -v -H 'Accept: application/json'
    -u 'client-id:client-secret'
    'https://user.gini.net/oauth/token?grant_type=client_credentials'
the successful response will have HTTP status 200 and the client access token 1eb7ca49-d99f-40cb-b86d-8dd689ca2345 will be returned

{
  "access_token":"1eb7ca49-d99f-40cb-b86d-8dd689ca2345",
  "token_type":"bearer","expires_in":43199,"scope":"read"
}

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.

//create a new user

curl -v -X POST --data '{"email":"random@example.org", "password":"geheim"}'
    -H 'Content-Type: application/json'
    -H 'Accept: application/json'
    -H 'Authorization: BEARER 1eb7ca49-d99f-40cb-b86d-8dd689ca2345'
    'https://user.gini.net/api/users'

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.

//the above command creates a new user random@example.org with password geheim. If the creation was successful, the HTTP response has status 201 and contains the Location header pointing to the new user. Your client is now allowed to create a new user authorized by the client access token.

//login as a new user

curl -v -X POST --data-urlencode 'username=random@example.org'
    --data-urlencode 'password=geheim'
    -H 'Content-Type: application/x-www-form-urlencoded'
    -H 'Accept: application/json' -u 'client-id:client-secret'
    'https://user.gini.net/oauth/token?grant_type=password'

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.

//use the access token you obtained to make API requests

GET /documents HTTP/1.1
Host: pay-api.gini.net
Authorization: BEARER 760822cb-2dec-4275-8da8-fa8f5680e8d4
Accept: application/vnd.gini.v1+json
Connection: close