LaunchKey SDK for Python

Note

This SDK version is intended for use with Services utilizing the LaunchKey Mobile Authenticator or White Label Authenticators utilizing White Label Directories created before 02/14/2017 for authorization. If you are not sure which SDK version to use, it will likely be this one.

Use this SDK to interact with the LaunchKey API in your Python 2.x application.

Before you can begin using the LaunchKey API, you need a service. If you have not created a service yet, you can use our Getting Started Guide to create one.

Installation

Download Source

LaunchKey Python SDK on GitHub

Do note that only release versions below 2.0.0 will work based on this current documentation. All versions above are for the LaunchKey White Label Subscriber SDK for Python.

Easy Install

easy_install launchkey-python

PIP

pip install launchkey-python

Create A LaunchKey API Object

Instantiate the launchkey.API object with your Service key, secret key and private key available from the Service details page of your LaunchKey Service.

Parameters

app_key:integer Unique 10-digit Service key from your service details page in dashboard
secret_key:string Secret key from your service details page in dashboard
private_key:string Retrieve private key from private.key

Example

# Import Python library
import launchkey

app_key = 1234567890

secret_key = "SECRET_KEY"

private_key = open("/path/to/private.key", "r").read()

api = launchkey.API(app_key, secret_key, private_key)

Authenticating A User

To authenticate a user, use the authorize() method with the user's LaunchKey username. Optionally, set session = False for a transactional authentication request (see explanation below). If the request is successfully sent, the be the auth_request token which you'll use to reference this auth request in subsequent calls.

Sessions vs. Transactions

Auth requests (authentication requests) can be designated as sessions or transactions based on the needs of your service. Sessions should be used when the user will have the ability to end an active session and log out (e.g. signing in and out of a website or app), whereas transactions are inactive one-way authorizations where the situation doesn't merit the need for clearing a session and logging out (e.g. approving receipt of a package). Within the Mobile Authenticator App, the end user will see a blue dot next to active sessions and a grey dot next to inactive transactions. Sessions are default.

Definition

api.authorize(username, session, user_push_id)

Parameters

username:string Username, user push ID, or end-user identifier for the user
session:boolean (True) True to specify session auth type, False for transaction auth type
user_push_id:boolean (True) True to return a custom user id.

Return

A string whose value is the auth_request token

Example Request

# Set session = False for a transactional auth request
session = True
#Set user_push_id to True if you would like to be returned a value that can be used to push requests to the user in the future
user_push_id = False
auth_request = api.authorize("username", session, user_push_id)

Determine Status Of Auth Request

Once you've sent a launch (python authorize) request to a user, you'll need to check the status of that request to determine whether or not the user has responded. If they have responded, the response will include the auth package containing the user's encrypted response. If they haven't responded, you'll see message: "pending response..." returned in the JSON. You should keep polling until an auth package is returned. Auth requests remain valid for 5 minutes.

Definition

api.poll_request(auth_request)

Parameters

auth_request:string The request-specific token

Returns

A Dict with the following attributes:

auth:string Encrypted and Base64 Encoded response package
user_hash:string The unique string you will use to identify the user in the future. If you are implementing server side events (callbacks), you will need to store this value with the associated auth_request value to properly complete the logout event processing.
organization_user:string This value will only be returned if the app is under an organization. It is the unique string that identifies the user across the entire organization
user_push_id:string This value will only be returned is user_push_id is True requested during an python authorize call. It is the unique value to initiate an authorization request from the Service

Example Request

auth_response = api.poll_request(auth_request)

Example Completed Response

{
    "auth" : "R8p0TXubA+R4GlOXZlyIe5R+kG+6xPDMp43Y8vaIg4+3D1ZmANXYAMssM1apBo4\/1lWDaPyUYNJopgjnY2WK\/tjkeqgkvvtnSscYGY7\/W8VYjPfv3xA2ddr9YxfS0fQtxDUAyjnn+lbd7d8uziKpTcIx5DPZ1mJ1+d0UBmPbMUf4X8WO5c3sorX",
    "user_hash" : "HO38LVDKogEn4jzIOBgjOsXlDCoTDxUvmbEQDL2SAFh",
    "user_push_id" : "fF24D435sSd4gfdfdDIOBgjOsXlDCoTDxUvmbEQDL2SAFh"
}

Decrypt & Check Response

When the user responds, decrypt the auth package using the is_authorized() method. If authorized by the user, the boolean response will be True whereas a blocked or denied request will return boolean False.

If the boolean response is True, you should continue authenticating the user in your service or consider them logged in.

Definition

api.is_authorized(auth_request, auth)

Parameters

auth_request:string Request-specific token
auth:string Encrypted auth response from poll request

Returns

Boolean value depicting whether or not the user authorized the request.

Example

api.is_authorized(auth_request, auth_response['auth'])

When A User Logs Out

If a user logs out from within your service, you should inform our API so we can take your Service out of the user's authorization list.

Definition

api.logout(auth_request)

Parameters

auth_request:string Request-specific token

Returns

Boolean value of True on success and False on failure.

Example

api.logout(auth_request)

Server Side Events (Callbacks)

Server side events, or callbacks, occur out of band as asynchronous events and are triggered by user interaction with a mobile authenticator App. The user interactions that are currently handled are De-Orbit/De-Orbit All and Launch Response. The SDK provides two separate methods for dealing with each type of server side event described below. In order to implement server side events, an Internet accessible endpoint URL must be provided for the LaunchKey Engine to contact once a qualifying event has occurred.

Logout Event

When your service receives notification from the LaunchKey Engine that a user has logged out, call the clear() method to verify the logout. A logout event can be identified as it has a unique query parameter of clear as well as a signature query parameter that will be used to verify the request. Pass these values to the clear method to verify the and decrypt the logout request.

Once verified, the user_hash will be returned. This value will match the user_hash from and earlier poll_request call. Use this hash to determine which user within your system you need to log out. Once you've logged out the user, inform the LaunchKey API that the user has been successfully logged out by calling the logout method.

Definition

api.clear(clear, signature)

Parameters

clear:string De-orbit request package
signature:string Used to validate that the logout request came from LaunchKey

Returns

A user_hash string that uniquely identifies the user allowing for log out.

Example

api.clear(clear, signature)
api.logout(auth_request)

Auth Request Response Event

When your app receives notification from the LaunchKey Engine that a user has responded to an auth request, follow the same process as defined in Decrypt & Check Response to determine the user's response. An auth request response event can be identified as it has a unique query parameter of auth as well as auth_request and user_hash query parameters.

As with the poll_request call, you will need to store the user_hash with the auth_request if the user has authorized the request to properly handle a logout event.

User Contributed

LaunchKey links to user contributed code as a resource to its community. LaunchKey does not in any way guarantee or warrant the quality and security of these code bases. User contributed code is supported by the creators. If you do find a link from the site to user contributed code that is malicious or inappropriate in any way, please report that link to LaunchKey immediately and we will investigate the claim. Submit any issue to LaunchKey support at https://launchkey.com./support. ×