Habit Logo
Documentation Powered by ReDoc

Habit Distributor API (1.0)

Download OpenAPI specification:Download

E-mail: support@habit.io URL: https://www.habit.io

Habit Distributor API's allow insurance distributors to sell insurance products using Habit resources.

Authentication

OAuth2 Authorization

In order to gain access to the Habit API, clients must authenticate using the OAuth 2.0 protocol, in particular the Client credentials flow.

See POST /auth/oauth2/token for details on how to get a token.

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: /v3/auth/authorize
Refresh URL: /v3/auth/exchange
Scopes:
  • distributor -

    gives access to all endpoints

ApiKeyAuth

Security Scheme Type API Key
Header parameter name: X-API-Key

Accessing the API

In order to interact with the Habit API, clients must authenticate using the OAuth 2.0 protocol, in particular the Client credentials flow.

This call must be made using the /v3/auth/authorize endpoint, passing pre-generated\ncredentials, called client\_id and client\_secret.

Other required parameters are:

  • response_type, indicating the flow type, in this case client_credentials
  • scope, indicating the requested permissions, in this case manager or device
  • redirect_uri, in case the client needs to be redirect to a hosted callback
  • state, a value to be passed as part of the authorization result

The response will be populated with, at least, 4 main attributes:

  • access_token, the actual token to be used in subsequent calls
  • expires, the validity of the returned tokens
  • refresh_token, for refreshing this information, before expires is reached
  • endpoints, an object containing the HTTP and MQTT base URLs assigned to the requesting client

All subsequent calls must be directed to the base URL provided in endpoints.http and an Authorization header must be added to every API call, in the form of:

Authorization: Bearer {access_token}

Request parameters

PARAMETER TYPE DESCRIPTION
client_id uuid the client unique identifier, provided by the Habit self-care
client_secret string automatically generated hash, provide by the Habit self-care
redirect_uri uri URI to be provided to the user-agent as part of a 303 or 307 HTTP response
response_type string the OAuth 2.0 flow to be used
scope string a comma separated string of permissions to be associated with the token
state string a general purpose string that will be forwarded and added to the flow final result

Response fields

FIELD TYPE DESCRIPTION
access_token string the token to be used in subsequent calls to the API as part of an HTTP Authorization header
client_id uuid the client unique identifier
code string an exchange code, for usage with code flow requests
endpoints object HTTP and MQTT base URLs assigned to the requesting client
expires timestamp the expiration date for the provided tokens
grant_type string the type of grant flow used to generate the provided tokens
refresh_token string a token used with /v3/auth/exchange to retrieve fresh tokens, without the re-executing the entire flow
scope array granted permissions associated with the provided tokens
state string general purpose string forwarded by the client in the first flow call

Call using POST method

Request Body schema: application/json
client_id
required
string

Client ID from Selfcare

client_secret
required
string

Client Secret from Selfcare

response_type
required
string
scope
required
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "bef41164-90c6-11e7-a25d-97266664a105",
  • "client_secret": "tqypzi6q3faldgbrtyhbh6e2",
  • "response_type": "client_credentials",
  • "scope": "distributor"
}

Response samples

Content type
application/json
{
  • "access_token": "{access_token}",
  • "client_id": "bef41164-90c6-11e7-a25d-97266664a105",
  • "code": "{code}",
  • "endpoints":
    {},
  • "expires": "2020-12-31T00:00:00.000+0000",
  • "grant_type": "client_credentials",
  • "refresh_token": "{refresh_token}",
  • "scope":
    [
    ]
}

Call using GET method

query Parameters
client_id
required
string
Example: client_id=bef41164-90c6-11e7-a25d-97266664a105
client_secret
required
string
Example: client_secret=tqypzi6q3faldgbrtyhbh6e2
response_type
required
string
Example: response_type=client_credentials
scope
required
string
Example: scope=distributor
redirect_uri
string
state
string
header Parameters
Content-Type
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "access_token": "{access_token}",
  • "client_id": "bef41164-90c6-11e7-a25d-97266664a105",
  • "code": "{code}",
  • "endpoints":
    {},
  • "expires": "2020-12-31T00:00:00.000+0000",
  • "grant_type": "client_credentials",
  • "refresh_token": "{refresh_token}",
  • "scope":
    [
    ]
}

Renew token

Before the expiration timestamp returns as expired, the client should renew the access token by calling the /v3/auth/exchange endpoint, passing the refresh_token return with the call to /v3/auth/authorize.

The return will be exactly the same as the return by /v3/auth/authorize.

Request parameters

PARAMETER TYPE DESCRIPTION
client_id uuid the client unique identifier, provided by the Habit self-care
redirect_uri uri URI to be provided to the user-agent as part of a 303 or 307 HTTP response
refresh_token string the token provided as refresh_token in a previous call to /v3/auth/authorize
grant_type string the type of grant flow used to generate the provided tokens

Response fields

FIELD TYPE DESCRIPTION
access_token string the token to be used in subsequent calls to the API as part of an HTTP Authorization header
client_id uuid the client unique identifier
code string an exchange code, for usage with code flow requests
endpoints object HTTP and MQTT base URLs assigned to the requesting client
expires timestamp the expiration date for the provided tokens
grant_t