# Authentication Kiwi has a complete platform to manage user accounts. It supports different authentication platforms, such as email/password, msisdn (phone) and Facebook. ## Platform configuration ## Common All authentication response objects contain an extra status, called "authentication\_integration\_status", that contain extra information about the status of the operation. This field should be used for debugging purposes only. A summarized status will always be available at the given response object. Inside "authentication\_integration\_status" there will be 3 fields: code, name and description. For a list of all possible status, see: Example: ```javascript { "authentication_integration_status": { "code": 4, "name": "GENERIC_COULD_NOT_FIND_CREDENTIAL", "description": "Could not find information for the given credentials. Either a login with the given key does not exist or it does exist but the sent credentials were invalid" } } ``` ### Email + Password #### Forgot Password POST to: **Headers**: Content-Type: Application/json X-Kiwi-Application-Key: YOUR\_APPLICATION\_KEY **Request**: Json with field email. Example request: ```javascript { "email" : "email_teste@gmail.com" } ``` **Response**: Json with field status (alongside with authentication\_integration\_status), that is the id of the status. For a list of all existing status see: Example Response: ``` { "status" : 0, "authentication_integration_status": { "code": 0, "name": "GENERIC_SUCCESS", "description": "Success" } } ``` After the **Forgot Password** is initiated successfully, an email will be sent to the user with a link to change it's password. Using this token, another API call should be made, the **Reset Password** call #### Reset Password POST to **Headers:** Content-Type: Application/json X-Kiwi-Application-Key: YOUR\_APPLICATION\_KEY **Query Parameters:** * token: token sent on the email received by the user * password: new password to be set for this user * ipi: identity pool identifier. This value was also sent on the email received by the user * aid: application id. This value was also sent on the email received by the user After the request is processed the user will be redirected to a Success or to an Error URL, as configured on Kiwi's administrative platform. Also, a query parameter named **status** will be sent, with one of the following values: * SUCCESS * ERROR\_INVALID\_TOKEN * ERROR\_CREDENTIAL\_NOT\_FOUND * ERROR\_INTERNAL\_ERROR Example Request: Redirected to: #### Change Password POST to: **Headers**: Content-Type: Application/json X-Kiwi-Application-Key: YOUR\_APPLICATION\_KEY X-Auth-Token: **Request**: Json with field "new\_password". Example request: ```javascript { "new_password" : "123567" } ``` **Response**: Json with field status (alongside with authentication\_integration\_status), that is the id of the status. For a list of all existing status see: Example Response: ``` { "status" : 0, "authentication_integration_status": { "code": 0, "name": "GENERIC_SUCCESS", "description": "Success" } } ``` ### MSISDN + Pincode TBD ### Facebook TBD ### SBT TBD ### UOL TBD ## Special flows ### Smart TV Kiwi can use pincodes to perform the authentication. For instance, it can be very hard to input email and password on a Smart TV using a remote controller. Using this flow, you can show a pincode to your user on the TV and ask him to input it on his device. Kiwi will provide an authentication token to the TV, so it'll be able to access the user data, such as subscriptions, account context, etc. #### Generating a ticket (create\_ticket) > A ticket holds the data that Kiwi uses to associate the pairing device with an account. When generating a ticket, Kiwi will generate a random pincode, that should be presented to the user. **Method:** POST **Endpoint:** `https://api.kwsdk.io/api/1.0/authentication/smarttv/create_ticket` **Query params:** none **Headers:** ``` Content-Type: application/json X-Kiwi-Application-Key: YOUR_APPLICATION_KEY ``` **Request body:** The request body accepts an (optional) `extra_info` parameter, containing a key-value map (only strings are accepted for both keys and values). The keys/values stored won't be validated (i.e. this field stores additional metadata that won't be used as part of the pairing process, being useful for the purpose of generating usage reports). The extra info will be saved alongside the generated ticket and will be included as part of the payload of `SMARTTV_ACCOUNT_PAIRED` events. ```javascript { "extra_info": { "brand": "Samsony", "model": "ABC-123KM", "key": "value" } } ``` The response is a JSON with the following fields: | field | optional? | description | | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | operation\_status | NO | The operation status (specified below). | | message | NO | A description (in english) explaining the motive of the **operation\_status**. Useful for debugging purposes. | | ticket\_id | YES | The ticket id that should be sent on the refresh\_ticket API to retrieve updated info about the ticket. Only returned when operation\_status = SUCCESS. | | pin | YES | The generated pin that should be input by the user. Only returned when operation\_status = SUCCESS. | | operation\_status | name | description | | ----------------- | ------------------------------- | ----------------------------------------------------------------------------------- | | 0 | SUCCESS | The ticket was created successfully. | | 2 | MISSING\_IDENTITY\_POOL | The application requesting the ticket lacks of an identity pool configuration. | | 3 | MISSING\_SMARTTV\_CONFIGURATION | The application requesting the ticket lacks of the Smart TV platform configuration. | #### Refreshing a ticket (refresh\_ticket) > You need to poll this API to know if the ticket is still valid and receive an authentication token, when the user inputs the pincode. **Method:** GET **Endpoint:** `https://api.kwsdk.io/api/1.0/authentication/smarttv/refresh_ticket` **Query params:** | field | optional? | value | | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | | ticket\_id | NO | The ticket\_id returned on a previous call to create\_ticket API or new\_ticket\_id returned on a previous call to refresh\_ticket API. | **Headers:** ``` X-Kiwi-Application-Key: YOUR_APPLICATION_KEY ``` The response is a JSON with the following fields: | field | optional? | description | | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | operation\_status | NO | The operation status (specified below). | | message | NO | A description (in english) explaining the motive of the **operation\_status**. Useful for debugging purposes. | | ticket\_status | YES | The current status of the ticket. Only returned when operation\_status = SUCCESS. | | new\_ticket\_id | YES | The new ticket id that should be sent on the refresh\_token API to retrieve updated info about the ticket. Only returned when operation\_status = SUCCESS and ticket\_status = NEW\_TICKET. | | new\_pin | YES | The new generated pin that should be input by the user. Only returned when operation\_status = SUCCESS and ticket\_status = NEW\_TICKET. | | operation\_status | name | description | | ----------------- | ------------------------------- | ----------------------------------------------------------------------------------- | | 0 | SUCCESS | The ticket was refreshed successfully. | | 1 | TICKET\_NOT\_FOUND | The requested ticket does not exist. | | 2 | MISSING\_IDENTITY\_POOL | The application requesting the ticket lacks of an identity pool configuration. | | 3 | MISSING\_SMARTTV\_CONFIGURATION | The application requesting the ticket lacks of the Smart TV platform configuration. | | ticket\_status | name | description | | -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | PENDING | The ticket wasn't redeemed yet. | | 2 | CONFIRMED | The user already redeemed this ticket. | | 3 | EXPIRED | The ticket expired. If you receive this status, you will need to perform another call to create\_ticket API to get a new ticket. | | 4 | NEW\_TICKET | The ticket expired, but Kiwi already generated a new ticket and pincode. You need to update the pincode being shown to the user. Consecutive calls to refresh\_ticket API need to use the new ticket id returned. If you call the refresh\_ticket API again with the old ticket id instead of the new, Kiwi will return EXPIRED status. | **Response headers:** If ticket\_status = CONFIRMED, Kiwi will return an authentication token *once*. You should store the token and use it when making calls to Kiwi (e.g. subscriptions). If you try to refresh a CONFIRMED ticket twice, the second refresh call WON'T return the authentication token. ``` X-New-Auth-Token: AUTH_TOKEN ``` #### Redeeming a ticket (redeem\_ticket) *This API will be soon available on both iOS and Android SDKs.* **Method:** GET **Endpoint:** `https://api.kwsdk.io/api/1.0/authentication/smarttv/redeem_ticket` **Query params:** | field | optional? | value | | ----- | --------- | ------------------------- | | pin | NO | The pin input by the user | **Headers:** ``` X-Kiwi-Application-Key: YOUR_APPLICATION_KEY X-Auth-Token: AUTH_TOKEN ``` The response is a JSON with the following fields: | field | optional? | description | | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------- | | operation\_status | NO | The operation status (specified below). | | message | NO | A description (in english) explaining the motive of the **operation\_status**. Useful for debugging purposes. | | operation\_status | name | description | | ----------------- | ------------------------------- | ----------------------------------------------------------------------------------- | | 0 | SUCCESS | The ticket was refreshed successfully. | | 1 | TICKET\_NOT\_FOUND | The requested ticket does not exist. | | 2 | MISSING\_IDENTITY\_POOL | The application requesting the ticket lacks of an identity pool configuration. | | 3 | MISSING\_SMARTTV\_CONFIGURATION | The application requesting the ticket lacks of the Smart TV platform configuration. | | 100 | INVALID\_AUTH\_TOKEN | The authentication token is either missing or invalid. | | 101 | TICKET\_ALREADY\_REDEEMED | The ticket was already redeemed. | | 102 | TICKET\_ALREADY\_EXPIRED | The ticket expired. | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://movile.gitbook.io/kiwi-manual/authentication.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.