User Center API¶

Gini’s User Center offers an API, e.g. to programmatically create new Gini accounts and to make API requests on behalf of a created user.

Note

Access to the User Center API is restricted to selected clients only.

Client Authentication¶

All access to the User Center API requires client authentication. A client can authenticate itself with the Client Credentials Grant described in RFC 6749. In short, the client exchanges its client ID and client secret for an access token.

Request¶

To get a client access token, do a GET request to /oauth/token?grant_type=client_credentials. The request must contain a HTTP basic access authorization header, with the client ID as username and the client secret as password.

Example¶

curl -v -H 'Accept: application/json' -u 'client-id:secret' 'https://user.gini.net/oauth/token?grant_type=client_credentials'

GET /oauth/token?grant_type=client_credentials HTTP/1.1
Authorization: Basic Y2xpZW50LWlkOnNlY3JldA==
Host: user.gini.net
Accept: application/json

Example response¶

{"access_token":"74c1e7fe-e464-451f-a6eb-8f0998c46ff6","token_type":"bearer","expires_in":3599}

The client can now use the returned access token to make requests to the User Center API, by sending the token as a bearer token in the Authorization request header:

GET /api/users/c1e60c6b-a0a4-4d80-81eb-c1c6de729a0e HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Accept: application/json

Authenticating on behalf of a user¶

The Resource Owner Password Credentials Grant can be used to exchange a user’s email address and password with an access token. The access token can then be used to make requests to the Gini API on behalf of the user.

Request¶

Key	Description
`username`	The user’s email address.
`password`	The user’s password.

Note that the client must authenticate itself using HTTP basic access authentication with its ID as username and its secret as password.

Example¶

curl -v -X POST --data-urlencode 'username=some_user@example.com' --data-urlencode 'password=supersecret' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' -u 'client-id:secret' 'https://user.gini.net/oauth/token?grant_type=password'

POST /oauth/token?grant_type=password HTTP/1.1
Authorization: Basic Y2xpZW50LWlkOnNlY3JldA==
Host: user.gini.net
Accept: application/json
Content-Type: application/x-www-form-urlencoded

username=some_user@example.com&password=supersecret

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 the Gini API on behalf of the user. See Making API requests for details.

Creating a new user¶

To create a new user, submit a POST request to /api/users.

Request¶

Key	Description
`email`	The new user’s email address (will be used as login username)
`password`	The new user’s password. Must be at least 6 characters long.

Example request¶

curl -v -X POST --data '{"email":"some_user@example.com", "password":"supersecret"}' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6' 'https://user.gini.net/api/users'

POST /api/users HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Content-Type: application/json

{"email":"some_user@example.com","password:"supersecret"}

Example response¶

HTTP/1.1 201 Created
Location: https://user.gini.net/api/users/c1e60c6b-a0a4-4d80-81eb-c1c6de729a0e
Content-Length: 0

If the request entity was considered invalid (missing fields, password less than 6 chars etc.) or a user with that email address already exists, the API responds with 400 Bad Request.

Retrieving user information¶

Information about a user can be retrieved with a GET request on /api/users/{userId}

Example request¶

GET /api/users/88a28076-18e8-4275-b39c-eaacc240d406 HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Accept: application/json

Response¶

Key	Description
`id`	Unique User ID.
`email`	The user’s email address.

Example¶

{"id":"88a28076-18e8-4275-b39c-eaacc240d406","email":"some_user@example.com"}

Changing a user’s password and/or email¶

A user’s password and/or email can be changed with a PUT request to /api/users/{userId}. To update a user’s password and/or email, the current password/email must be provided.

Request¶

Key	Description
`oldPassword`	The user’s current password.
`password`	The password to which the user’s password should be changed to.
`oldEmail`	The user’s current email.
`email`	The email to which the user’s email should be changed to.

Example request¶

PUT /api/users/c1e60c6b-a0a4-4d80-81eb-c1c6de729a0e HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Content-Type: application/json

{"oldPassword":"supersecret","password:"anothersecret"}

or

{"oldEmail":"old@email.com","email:"my.new@email.com"}

or

{"oldPassword":"supersecret","password:"anothersecret","oldEmail":"old@email.com","email:"my.new@email.com"}

Deleting a user¶

An existing user can be deleted with a DELETE request to /api/users/{userId}. This also deletes all data associated with that user (e.g. access tokens, documents and extractions).

Example request¶

DELETE /api/users/16aecc72-8032-4df6-9686-eaf4ec9532b8 HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Content-Type: application/json