Page Properties | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
Table of Contents |
---|
As mentioned above, Gini Pay API supports different authentication flows, depending on the use case. The API differentiates between anonymous and derived users. Client credentials (that you received when you registered your application) support either derived or anonymous user flows.
Anonymous users are identified by username and password. You create them explicitly for your untrusted devices.
Derived users are identified by their username only, specified by
X-User-Identifier
header. The value is up to you, usually a stable hash of your internal user identifier. A derived user is automatically created if it doesn't exist already. It is unique for the client.
There are currently 4 different authentication flows possible with our API.
Communication from a trusted device using a derived user
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": [ {...}, {...}, ... ] } |
Communication from an untrusted device using a derived user
To communicate with Gini Pay API from untrusted devices, 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' |
Communication from both trusted and untrusted devices using a derived user
When you communicate with our API from a trusted device using client credentials (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.
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' |
Communication from an untrusted device using an anonymous user
This is the only flow that requires communication with two APIs: the Pay API and the User Center API. This flow is done in 4 steps:
Obtain the client token using client credentials
Create a new user using the client token
Log in on behalf of the user and acquire an access token
Make API requests with the access token
Access tokens expire. So the last two steps should be repeated to refresh the token and hand it over to the untrusted device for use.
Code Block |
---|
//Step 1. Get client token from a trusted device curl -v -H 'Accept: application/json' -u 'client-id:client-secret' 'https://user.gini.net/oauth/token?grant_type=client_credentials' //example response { "access_token":"6c470ffa-abf1-41aa-b866-cd3be0ee84f4", "token_type":"bearer", "expires_in":3599 } //Step 2. Use the client token above to create user with arbitrary username and password (user usually identifies the physical device e.g mobile phone) curl -v -X POST --data '{"email":"random@example.org", "password":"geheim"}' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: BEARER 6c470ffa-abf1-41aa-b866-cd3be0ee84f4' 'https://user.gini.net/api/users' //example response HTTP/1.1 201 Created Location: https://user.gini.net/api/users/6407244f-9edf-4119-8641-be18c39226d8 Content-Length: 0 //Step 3. Authenticate on behalf of the user using client credentials and acquire the access token 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' //example response { "access_token":"6c470ffa-abf1-41aa-b866-cd3be0ee84f4", "token_type":"bearer", "expires_in":3599 } //Step 4. Communicate with the API from an untrusted device with the acquired access token curl -X GET -i https://pay-api.gini.net/documents -H 'Authorization: BEARER 6c470ffa-abf1-41aa-b866-cd3be0ee84f4' -H 'Accept: application/vnd.gini.v1+json' |