...
Communication from a trusted device using a derived user
Basic Authentication
Communicate with Gini Pay API using client credentials (basic authentication) from a trusted device that is your trusted backend. A derived user is automatically created if it doesn't exist already.
...
| Code Block | ||
|---|---|---|
| ||
curl -v -H 'Accept: application/vnd.gini.v1+json'
-u 'client-id:client-secret'
-H 'X-User-Identifier: user_hash_123'
https://pay-api.gini.net/documents
//example response
{
"documents": [
{...},
{...},
...
]
} |
JWT Authentication
Communicate with Gini Pay API using JWT access token from a trusted device that is your trusted backend. A derived user is automatically created if it doesn't exist already.
| Code Block | ||
|---|---|---|
| ||
//Upload document to Pay API with JWT access token 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 //example response { "documents": [ {...}, {...}, ... ] } |
...
Communication from an untrusted device using a derived user
Basic Authentication
To communicate with Gini Pay API from untrusted devices by using basic authentication, acquire a token from Gini Pay API for the user and hand it over to the untrusted device. The user is derived/created from X-User-Identifier header. The value is up to you, often a stable hash of your internal user identifier.
...
| Code Block | ||
|---|---|---|
| ||
//Acquire a token and hand it over to the untrusted device
curl -v -X POST
-H 'X-User-Identifier: user_hash_123'
-H 'Accept: application/vnd.gini.v1+json'
-u 'client-id:secret' 'https://pay-api.gini.net/login'
//example response
{
"access_Token": "S+YXT+XneST13aqoBRBgBiw6Quk=",
"token_type": "bearer",
"expires_in": 43199
}
//Query API with the acquired token
curl -X GET -i https://pay-api.gini.net/documents
-H 'Authorization: BEARER S+YXT+XneST13aqoBRBgBiw6Quk='
-H 'Accept: application/vnd.gini.v1+json' |
JWT Authentication
To communicate with Gini Pay API from untrusted devices by using JWT Authentication, acquire a JWT access token from your identity provider for the user, use this JWT access token to get Gini access token from Gini Pay API and hand it over to the untrusted device. The user is derived/created from x-user-identifier custom claim that is embedded in the JWT access token. The value is up to you, often a stable hash of your internal user identifier.
| Code Block | ||
|---|---|---|
| ||
//Acquire a Gini access token from JWT access token and hand it over to the untrusted device curl -v -X POST -H 'X-JWT-Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJpaURuUzZoaVU2MGFCNUVPUFZtQlhjRzZKaHFsenBxdlRKQVJ1SG5UWGVFIn0.eyJleHAiOjIwMjgwMjUzOTEsImlhdCI6MTcxMjY2NTM5MSwianRpIjoiN2RmZTVkYzYtMWIyYi00MzdhLWE2MTAtOWZmYWMwMGFlMTk1IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MTgwL3JlYWxtcy9TcHJpbmdCb290S2V5Y2xvYWsiLCJzdWIiOiJkZDJiYjg3Mi1iMTc2LTRkNjktYTcyOC1lMTMzNzRkOWJhNDYiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJsb2dpbi1hcHAiLCJzZXNzaW9uX3N0YXRlIjoiMjgxOTE5NDItYzc5ZS00ZTI0LTk5ODktNDQ4YjkzNWFjMmE2IiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwODEiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbInVzZXIiXX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCBtaWNyb3Byb2ZpbGUtand0Iiwic2lkIjoiMjgxOTE5NDItYzc5ZS00ZTI0LTk5ODktNDQ4YjkzNWFjMmE2IiwieC11c2VyLWlkZW50aWZpZXIiOiJ1c2VyMSIsInVwbiI6InVzZXIxIiwieC1jbGllbnQtc2VjcmV0IjoiY2xpZW50U2VjcmV0IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsIngtY2xpZW50LWlkIjoiY2xpZW50SWQiLCJuYW1lIjoiQmFuayBVc2VyIEZpcnN0IE5hbWUgQmFuayBVc2VyIExhc3QgTmFtZSIsImdyb3VwcyI6WyJ1c2VyIl0sInByZWZlcnJlZF91c2VybmFtZSI6InVzZXIxIiwiZ2l2ZW5fbmFtZSI6IkJhbmsgVXNlciBGaXJzdCBOYW1lIiwiZmFtaWx5X25hbWUiOiJCYW5rIFVzZXIgTGFzdCBOYW1lIiwiZW1haWwiOiJsb2NhbC1hZG1pbkBtYWlsLmNvbSJ9.MOOsftcPMA55aOGh9FwVXvW8Q-HfgFA9l7K9IaJJQQBkBkp4DfkO5ad9P17UWqhiLL20vjCVLP2Dv_fIx0lQQg2SZBBvKvyrssfI7XRTN4_aYVW-5-TVPGQiy_b-1iAQhZ9L6wGSlKUbrw5P_QockvkvqSlYs_LhMH7Rg6xjFVRMGzbAiQIY_8NpL5cRB8AxKJpepWKju4wnmeseoj9rnVqFfLodd7k6BYkTs52qcQj3d-6aZVeyGoEOU0xtFgGOUpwI_r_bh4EDq8zoTIsHwM5kx3AJL_BatdkQw5vj10GDtfmgd-oO2ABJHMnh15OawO9xRk5zY2kDcDM4R1LNOA' -H 'Accept: application/vnd.gini.v1+json' 'https://pay-api.gini.net/login' //example response { "access_Token": "S+YXT+XneST13aqoBRBgBiw6Quk=", "token_type": "bearer", "expires_in": 43199 } //Query Pay API with the acquired token curl -X GET -i https://pay-api.gini.net/documents -H 'Authorization: BEARER S+YXT+XneST13aqoBRBgBiw6Quk=' -H 'Accept: application/vnd.gini.v1+json' |
...
Communication from both trusted and untrusted devices using a derived user
When you communicate with our API from a trusted device using client credentials or JWT access token (option 1), a derived user is automatically created for a given X-User-Identifier when it's specified for the first time. From then on, the derived user stays fixed for this client ID and X-User-Identifier. You can also acquire an access token for this user, so it can be used by an untrusted device. This scenario is valid when you have both trusted and untrusted devices communicating with our API and you don't want client credentials stored on an untrusted device.
Basic Authentication
...
| Code Block | ||
|---|---|---|
| ||
//Derived user is automatically created for user_hash_789 first time client uses it from a trusted device
curl -v -H 'Accept: application/vnd.gini.v1+json'
-u 'client-id:client-secret'
-H 'X-User-Identifier: user_hash_789'
https://pay-api.gini.net/documents
//Trusted device can now acquire the token for an already existing user_hash_789
curl -v -X POST
-H 'X-User-Identifier: user_hash_789'
-H 'Accept: application/vnd.gini.v1+json'
-u 'client-id:secret' 'https://pay-api.gini.net/login'
//example response
{
"access_Token": "G+YXT+XneST13aqoBRBgBiw6Qza=",
"token_type": "bearer",
"expires_in": 43199
}
//Hand the acquired access token over to an untrusted device so that it can query API
curl -X GET -i https://pay-api.gini.net/documents
-H 'Authorization: BEARER G+YXT+XneST13aqoBRBgBiw6Qza='
-H 'Accept: application/vnd.gini.v1+json' |
JWT Authentication
| Code Block | ||
|---|---|---|
| ||
//Derived user is automatically created for user_hash_789 first time client uses it from a trusted device 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 //Trusted device can now acquire the token for an already existing user_hash_789 curl -v -X POST -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/login' //example response { "access_Token": "G+YXT+XneST13aqoBRBgBiw6Qza=", "token_type": "bearer", "expires_in": 43199 } //Hand the acquired access token over to an untrusted device so that it can query API curl -X GET -i https://pay-api.gini.net/documents -H 'Authorization: BEARER G+YXT+XneST13aqoBRBgBiw6Qza=' -H 'Accept: application/vnd.gini.v1+json' |
...
Communication from an untrusted device using an anonymous user
...