Download OpenAPI specification:Download
Habit Distributor API's allow insurance distributors to sell insurance products using Habit resources.
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:
|
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:
The response will be populated with, at least, 4 main attributes:
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}
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 |
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 |
client_id required | string Client ID from Selfcare |
client_secret required | string Client Secret from Selfcare |
response_type required | string |
scope required | string |
{- "client_id": "bef41164-90c6-11e7-a25d-97266664a105",
- "client_secret": "tqypzi6q3faldgbrtyhbh6e2",
- "response_type": "client_credentials",
- "scope": "distributor"
}
{- "access_token": "{access_token}",
- "client_id": "bef41164-90c6-11e7-a25d-97266664a105",
- "code": "{code}",
- "endpoints": {
- "mqtt": "mqtts://api.platform.habit.io:8881"
}, - "expires": "2020-12-31T00:00:00.000+0000",
- "grant_type": "client_credentials",
- "refresh_token": "{refresh_token}",
- "scope": [
- "distributor"
]
}
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 |
Content-Type required | string Default: application/json |
{- "access_token": "{access_token}",
- "client_id": "bef41164-90c6-11e7-a25d-97266664a105",
- "code": "{code}",
- "endpoints": {
- "mqtt": "mqtts://api.platform.habit.io:8881"
}, - "expires": "2020-12-31T00:00:00.000+0000",
- "grant_type": "client_credentials",
- "refresh_token": "{refresh_token}",
- "scope": [
- "distributor"
]
}
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.
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 |
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 |