Managing anonymous Gini accounts¶

For best results, the Gini API must be able to track requests down to individual users for various reasons:

Users might have individual opinions on the type of documents or the correctness of certain values
To evaluate the correctness of feedback: the more users that submit the same value, the more correct it likely is.

Gini offers various ways to perform requests on behalf of individual users, without requiring physical user interaction. Depending on your use case and the architecture of your product, the following ways to authenticate to the Gini API are possible:

Direct communication from client devices to the Gini API

On first usage of the Gini API, your application creates an anomyous 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 the Gini API on an untrusted device.

This method is built-in into most of the Gini API SDKs.
Communication to the Gini API via a backend/gateway

Your application communicates with the Gini API via a common backend that runs on a trusted device. Each request states for which user a request is made using a user identifier devised by your application. No account management is required.

Communication to the Gini API via a backend/gateway¶

This authentication scheme is based on HTTP Basic Authentication. Your application uses HTTP Basic Authentication to authenticate itself against the Gini API. In addition to the Authorization header, another header called X-User-Identifier is sent per request. This header is used by the Gini API to distinguish 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 has to be unique
Once determined for a user, the identifier must remain the same

For example, to get the list of user1‘s documents, use the following request:

curl -v -H 'Accept: application/vnd.gini.v1+json' -u 'client-id:client-secret' -H 'X-User-Identifier: user1' https://api.gini.net/documents

Warning

Keep your client credentials secret at all times! Otherwise third parties might have access to sensitive data if they are able to guess how your application generates user identifiers.

Note

This authentication scheme has to be enabled for your client by Gini. Please contact us if you intend to use this feature.

Direct communication from client devices to the Gini API¶

Gini offers the User Center API to work with Gini users. This step-by-step guide outlines how to create and use a new (anonymous) Gini account. See the links to the corresponding sections of the User Center API for details about each step.

Obtain a client token

Before you are able to use the User Center API, you need to obtain a client access token. This client access tokes authorizes your client (i.e. your application) against the User Center API.

It is assumed that you have a client ID client-id and a client secret client-secret. Authorized by those (with HTTP Basic Authentication), your client can obtain a client access token using the following request:
```
curl -v -H 'Accept: application/json' -u 'client-id:client-secret' 'https://user.gini.net/oauth/token?grant_type=client_credentials'
```
In case of success, the response will have HTTP status 200 and 1eb7ca49-d99f-40cb-b86d-8dd689ca2345 is returned as client access token:
```
{"access_token":"1eb7ca49-d99f-40cb-b86d-8dd689ca2345","token_type":"bearer","expires_in":43199,"scope":"read"}
```
Create a new user

Your client is now allowed to create a new user, authorized by the client access token.

Two values are required for a new user: A username and a password. The username must be a syntactically 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 to use for your app’s user accounts.
```
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'
```
This will create a new user random@example.org with password geheim. If the creation is successful, the response will have HTTP status 201 and the response contains a Location header that points to the new user.
Log in as that 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'
```
Note that this request requires HTTP Basic Authentication again, with the client ID as username and the client secret as password. It does not require a client access token.

The result is an access token that can be used to make API requests on behalf of the user. See Making API requests for details.