| Page Properties | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
...
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:
...
| Code Block | ||
|---|---|---|
| ||
//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.
| Code Block | ||
|---|---|---|
| ||
{
"alg": "RS256",
"typ": "JWT",
"kid": "iiDnS6hiU60aB5EOPVmBXcG6JhqlzpqvTJARuHnTXeE"
} |
The payload of the JWT access token should at least include the following claims. The values of x-user-identifier, x-client-idand x-client-secretare the same as in the basic authentication schema.
| Code Block | ||
|---|---|---|
| ||
{
...
"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:
| Code Block | ||
|---|---|---|
| ||
//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:
| Code Block |
|---|
curl --location "http://<your-identity-provider-jwk-set-url>" |
Sample response from jwk-set endpoint:
| Code Block | ||
|---|---|---|
| ||
{
"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
...
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.
| Code Block | ||
|---|---|---|
| ||
//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"
} |
...