Versions Compared

Old Version 4

changes.mady.by.user Former user

Saved on

compared with

New Version Current

changes.mady.by.user Vedat Ekiz

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Page Properties
hiddentrue

Status

Status
colourPurpleYellow
titlestartedfor review

Approver

Pavel Shkadzko

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.

...

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
languagejson
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.

x-jwt-option-1.1.pngImage Added

Code Block
languagejson
//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, usually often a stable hash of your internal user identifier.

...

Code Block
languagejson
//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. refresh_token is optional.

{
  "access_token": "S+YXT+XneST13aqoBRBgBiw6Quk=",
  "refresh_token": "5uKtqmB5ZMRajlauEl_SkxQkGWkM-9",
  "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.

x-jwt-option-2.1.pngImage Added

Code Block
languagejson
//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. refresh_token is optional.

{
  "access_Token": "S+YXT+XneST13aqoBRBgBiw6Quk=",
  "refresh_token": "5uKtqmB5ZMRajlauEl_SkxQkGWkM-9",
  "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'

If your client is configured, you will also receive a refresh_token in the /login response.

...

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
languagejson
//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. refresh_token is optional.

{
  "access_token": "G+YXT+XneST13aqoBRBgBiw6Qza=",
  "refresh_token": "5uKtqmB5ZMRajlauEl_SkxQkGWkM-9",
  "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

x-jwt-option-3.1.pngImage Added

Code Block
languagejson
//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. refresh_token is optional.

{
  "access_token": "G+YXT+XneST13aqoBRBgBiw6Qza=",
  "refresh_token": "5uKtqmB5ZMRajlauEl_SkxQkGWkM-9",
  "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'

If your client is configured, you will also receive a refresh_token in the /login response.

...

Communication from an untrusted device using an anonymous user

...

  1. Obtain the client token using client credentials

  2. Create a new user using the client token

  3. Log in on behalf of the user and acquire an access token

  4. 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'