Authorization Implementation Guide¶

Warning

While the information in this guide is not wrong, Gini highly recommends the use of anonymous accounts for now. See Managing anonymous Gini accounts for information how to create and use anonymous accounts.

All API requests require an authenticated Gini user. You can authorize against the API using OAuth 2.0.

The redirect URI¶

In short, the redirect URI is your application’s starting point. After the Gini Authorization Server finished the authorization interaction with your application’s user, it will redirect them back to your application at the given redirect URI.

Requirements for a redirect URI:

Must be an absolute URI

Must not include a fragment component (see RFC 3986)

May include a query component (see RFC 3986) (application/x-www-form-urlencoded formatted)

Implement an authentication flow¶

Gini currently supports two OAuth 2.0 authentication flows:

Server-Side Flow (called Authorization Code Grant in RFC 6749): Should be used when you make calls to the Gini API from a (web application) server.
Client-Side Flow (called Implicit Grant in RFC 6749): Should be used when you make calls to the Gini API from a client, such as a browser application or a native mobile application.

Server-Side Flow¶

The authentication flow begins with your application redirecting the user to the Gini Authorization Server:

https://user.gini.net/oauth/authorize?response_type=code&client_id={clientId}&redirect_uri={redirectUri}&state={state}

The URI takes the following parameters:

Name	Description
client_id	The client ID you received from Gini.
redirect_uri	Where to redirect after the user completed the authorization. Must be one of the values that you provided when you registered your application.
state (optional)	Some random string (should be unguessable) to protect against cross-site request forgery attacks.

Example request¶

GET /oauth/authorize?response_type=code&client_id=example-clientid&state=uiaeo&redirect_uri=https%3A%2F%2Fapp.example.com%2F HTTP/1.1
Host: user.gini.net
Connection: close

After the Gini user successfully finished the authorization process, the Gini Authorization Server will redirect them back to your application using redirect_uri. The following query parameters are added to redirect_uri:

Name	Description
code	A temporary authorization code
state	The state your application provided in the previous step.

If the value of state doesn’t match with the value that your application has provided in the previous step, the request has been created by some third party application, hence the authentication process should be aborted.

Example response¶

HTTP/1.1 303 See Other
Location: http://example.com/?code=117587e6-4ea5-49ce-a90b-a66d232dfa26&state=uiaeo

Your application then exchanges the received authorization code for an access token:

POST https://user.gini.net/oauth/token

The request takes the following parameters, encoded using the application/x-www-form-urlencoded format:

Name	Description
grant_type	Must be set to `authorization_code`.
code	The authorization code received from the Gini Authorization Server.
redirect_uri	Only required if the `redirect_uri` parameter was included in the authorization request (and then the values must be identical).

The request must contain a HTTP basic access authorization header, with the client ID as username and the client secret as password.

Example request¶

POST /oauth/token HTTP/1.1
Host: user.gini.net
Authorization: Basic ZXhhbXBsZS1jbGllbnRpZDpzZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
Connection: close

code=117587e6-4ea5-49ce-a90b-a66d232dfa26&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fapp.example.com%2F

Token response¶

If the access token request is valid and authorized, the response will be a JSON-encoded object with the following fields:

Name	Type	Description
access_token	string	The access token that can be used for API requests.
token_type	string	The type of the access token. Will be `bearer`.
expires_in	integer	How long the access token is valid (in seconds). Defaults to 300.
refresh_token	string	Refresh token that can be used to get a new access token.

Example token response¶

{"access_token":"760822cb-2dec-4275-8da8-fa8f5680e8d4","token_type":"bearer","expires_in":300,"refresh_token":"46463dd6-cdbb-440d-88fc-b10a34f68b26"}

Error response¶

In case there was a problem when verifying the token request (e.g. invalid authorization code), the authorization server responds with an HTTP 400 (Bad Request) status code and returns a JSON-encoded object with the following fields:

Name	Type	Description
error	string	An error code. See RFC 6749 for a list.
error_description	string	Human-readable error description.

Refreshing an access token¶

Once an access token has expired (see the expires_in field of a token response), your application can request a new access token using the refresh token:

POST /oauth/token HTTP/1.1
Host: user.gini.net
Authorization: Basic ZXhhbXBsZS1jbGllbnRpZDpzZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
Connection: close

grant_type=refresh_token&refresh_token=46463dd6-cdbb-440d-88fc-b10a34f68b26

The request takes the following parameters:

Name	Description
grant_type	Must be `refresh_token`.
refresh_token	The refresh token.

The request must contain a HTTP basic access authorization header, with the client ID as username and the client secret as password.

The response is a new token. See Token response for details.

Client-Side Flow¶

Like the Server-Side Flow, the authentication flow begins with your application redirecting the user to the Gini Authorization Server:

https://user.gini.net/oauth/authorize?response_type=token&client_id={clientId}&redirect_uri={redirectUri}&state={state}

The URI takes the following parameters:

Name	Description
client_id	The client ID you received from Gini.
redirect_uri	Where to redirect after the user completed the authorization. Must be one of the values that you provided when you registered your application.
state (optional)	Some random string (should be unguessable) to protect against cross-site request forgery attacks.

Example request¶

GET /oauth/authorize?response_type=token&client_id=example-clientid&redirect_uri=https%3A%2F%2Fapp.example.com%2F&state=uiaeo HTTP/1.1
Host: user.gini.net
Connection: close

After the Gini user successfully finished the authorization process, the Gini Authorization Server will redirect them to your application (using the redirection URI you provided when you registered your application). The following parameters are passed in the fragment component of the redirection URI, encoded using the application/x-www-form-urlencoded format:

Name	Type	Description
access_token	string	The access token that can be used for API requests.
token_type	string	The type of the access token. Will be `bearer`.
expires_in	integer	Unix timestamp (in milliseconds) when the token will expire.
state	string	The state your application provided in the previous step.

Example response¶

HTTP/1.1 303 See Other
Location: http://example.com/#access_token=760822cb-2dec-4275-8da8-fa8f5680e8d4&token_type=bearer&expires_in=1391519957867&scope=read,write&state=uiaeo

If the value of state doesn’t match with the value that your application has provided in the previous step, the request has been created by some third party application. Your application should not use the received access token to make any API requests.

Making API requests¶

Use the access token you obtained to make requests to the API, by sending the access token as a bearer token in the Authorization request header:

GET /documents HTTP/1.1
Host: api.gini.net
Authorization: BEARER 760822cb-2dec-4275-8da8-fa8f5680e8d4
Accept: application/vnd.gini.v1+json
Connection: close

There is also the possibility to pass the authorization token via the query parameter token:

GET /documents?token=760822cb-2dec-4275-8da8-fa8f5680e8d4 HTTP/1.1
Host: api.gini.net
Accept: application/vnd.gini.v1+json
Connection: close