home api list

Hexostore API Documentation

OAuth 2 Support

An helpful outline of OAuth2 operations can be found at http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified. The full specification can be found here: https://tools.ietf.org/html/rfc6749

Your application must use only one of the following supported grant types: authorization_code, implicit, and password. Each grant type serves a different level of trust.

The authorization_code grant type is for applications that can keep a secret, i.e. are not distributed. This is mainly web-based applications where the code remains on the web server.

The implicit grant type is for applications that cannot keep a secret, i.e. anything that is distributed. This includes mobile applications and applications that wish to make AJAX requests directly from a user's browser.

The password grant type is supported but will only work in limited use cases. It provides a simplified method for API users who wish to access only their own data. This grant type uses a very simple flow for obtaining an access token, but that token will only authenticate the user who owns the OAuth2 Client. In other words, if you wish many users to use your application, this will not work.

Grants Types

`authorization_code` grant type

Authorization code can be used for web and mobile applications. however the client_secret cannot be stored in the device nor the web client. It should be stored on a secure server instead.

To authorize a user, send them to:

GET https://api.hexoskin.com/api/connect/oauth2/auth/?response_type=code&
    client_id=CLIENT_ID&
    redirect_uri=REDIRECT_URI&
    scope=SCOPE&
    state=UNIQUE_STATE_STRING

Where CLIENT_ID and CLIENT_SECRET is your OAuth2 client authentication information, REDIRECT_URI is one of your redirect URIs registered with Hexoskin, SCOPE is the desired scope, and UNIQUE_STATE_STRING is a unique string for preventing cross-site request forgery as described in https://tools.ietf.org/html/rfc6749#section-10.12.

Users will then be redirected to the specified REDIRECT_URI.

The response will be one of two possible results:

The user was successfully authenticated and approved your application. You will have an authorization code.
```
[REDIRECT_URI]?code=AUTH_CODE
```
The user did not approve the application (yours or Hexoskin in general) or another error of some kind occured.
```
[REDIRECT_URI]?error=error%20message%20here
```

If you have successfully obtained an authorization code, you may exchange it for a token by POSTing an authenticated request to:

POST https://api.hexoskin.com/api/connect/oauth2/token/

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=REDIRECT_URI

If all went well, you well receive an access token:

{
    "resource_uri": "/api/oauth2token/[id]/"
    "access_token": "tokenstring",
    "refresh_token": "refreshtokenstring",
    "scopes": ["valid", "scopes"],
    "user": "/api/user/[user_id]/",
    "expires_in": int
}

If an error of some kind occured, instead of the token you will receive an error message:

{
    "error": "description of the error"
}

`implicit` grant type

the implicit grant type is used for applications that cannot keep the client_secret. It is used for client-only application.

example :

an android application that does not interact with a server
a client javascript application

To authorize an user, send them to:

GET https://api.hexoskin.com/api/connect/oauth2/auth/?response_type=token&
    client_id=CLIENT_ID&
    client_secret=CLIENT_SECRET&
    redirect_uri=REDIRECT_URI&
    scope=SCOPE&
    state=UNIQUE_STATE_STRING

If you do not specify a redirect_uri, users will be redirected to the first entry from your client's redirect_uris or, if none are defined, to the default Hexoskin landing page.

In either case, the response will be one of two possible results:

The user was successfully authenticated and approved your application. You can find the token in the hash fragment:
```
[REDIRECT_URI]#access_token=TOKEN_VALUE&token_type=Bearer&state=UNIQUE_STATE_STRING&expires_in=TTL&scope=SCOPE
```
The user did not approve the application (yours or Hexoskin in general) or another error of some kind occured.
```
[REDIRECT_URI]#error=ERROR_MSG&state=UNIQUE_STATE_STRING
```

`password` grant type

The password grant type is only used for personal or non-distributed application, because it requires the client to send the username and the password

To obtain an access token, POST an token-request as follows:

POST https://api.hexoskin.com/api/connect/oauth2/token/
client_id=CLIENT_ID&
client_secret=CLIENT_SECRET&
username=USERNAME&
password=PASSWORD&
scope=SCOPE&
grant_type=password

You'll receive the response in the body as JSON, a token if all went well, otherwise an error message,
identical to the code exchange in Web Applications.

Token handling

Getting a token through the token endpoint

Requesting a token through the token's endpoint https://api.hexoskin.com/api/connect/oauth2/token/ requires to pass the client_id and client_secret when doing a POST token request similar to the example above.

the supported format to do the request are json or text/plain

Using a token

To use a token (either just received from a authentication or cached from an earler session) send the token in the Authorization header. An example header would be:

Authorization: Bearer tokenvaluegoeshere;

If the request is rejected with a 401, the token is no longer valid. You will need to obtain a new token.

Using a refresh token

Refresh tokens allow you to generate a new access token easily without asking the user to authenticate your application a second time.

Use an authenticated request as follows to obtain a new access token:

POST https://api.hexoskin.com/api/connect/oauth2/token/

    grant_type=refresh_token&
    refresh_token=REFRESH_TOKEN&
    client_id=CLIENT_ID

Where REFRESH_TOKEN is the string you received in the refresh_token field with your latest access token. You will receive a new access token in the body of the response.

Refresh tokens are valid for 30 days and can only be used once. The new access token will contain another refresh token which you may continue to use.

Deleting a token

If you wish to disconnect the user, send a DELETE to the token's resource_uri.

DELETE https://api.hexoskin.com/api/accesstoken/[id]

where id is the token value

Mobile device handling

Handling redirect URL for mobile devices

if implicit or authorization_code is used, the flow will eventually use a redirect url to pass the authorization code or the token.

for security reasons, http and https are the only valid redirect url schemes. Thus, you cannot use a custom url scheme to capture redirects for your application

Instead it is recommended to use deep linking to hook your application to a redirect url.

Links: - Android - Ios