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: https://github.com/Movile/kiwi-modules/blob/72a01dc5579b37d7e2aaaec8131030676e933fc1/kiwi-module-authentication/src/main/java/com/movile/kiwi/auth/service/account/AuthenticationIntegrationStatus.java

Example:

{
    "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: https://api.kwsdk.io/api/1.0/authentication/email/forgot_password

Headers:

Content-Type: Application/json

X-Kiwi-Application-Key: YOUR_APPLICATION_KEY

Request:

Json with field email.

Example request:

{
    "email" : "[e-mail]"
}

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: https://github.com/Movile/kiwi-webservice/blob/24239702e3b41db9b1ed0c9f94f95042347ab008/kiwi-webservice-application/src/main/java/com/movile/kiwi/ws/web/controller/auth/email/to/ForgotPasswordOperationStatus.java

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 https://tools.kwsdk.io/api/1.0/auth/email_password/reset_password

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: https://tools.kwsdk.io/api/1.0/auth/email_password/reset_password?token=djsasiudhaisd&password=123456&ipi=8123123123&aid=3

Redirected to: https://my-app.com/Success?status=SUCCESS

Change Password

POST to: https://api.kwsdk.io/api/1.0/authentication/email/change_password Headers:

Content-Type: Application/json

X-Kiwi-Application-Key: YOUR_APPLICATION_KEY

X-Auth-Token:

Request:

Json with field "new_password".

Example request:

{
    "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: https://github.com/Movile/kiwi-webservice/blob/24239702e3b41db9b1ed0c9f94f95042347ab008/kiwi-webservice-application/src/main/java/com/movile/kiwi/ws/web/controller/auth/email/to/ChangePasswordOperationStatus.java

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.

{
    "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.