LaunchKey SDK for Python
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.
pip install launchkey-python
Create A LaunchKey API Object
launchkey.API object with your Service key, secret key and private key available from the Service
details page of your LaunchKey Service.
|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
# Import Python library
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.
api.authorize(username, session, user_push_id)
|username:||string Username, user push ID, or end-user identifier for the user
True to specify session auth type,
False for transaction auth type
|user_push_id:||boolean (True) True to return a custom user id.
A string whose value is the
# 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.
|auth_request:||string The request-specific token
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
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
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
If the boolean response is
True, you should continue authenticating the user in your service or consider them
|auth_request:||string Request-specific token
|auth:||string Encrypted auth response from poll request
Boolean value depicting whether or not the user authorized the request.
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
|auth_request:||string Request-specific token
Boolean value of
True on success and
False on failure.
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
When your service receives notification from the LaunchKey Engine that a user has logged out, call the
method to verify the logout. A logout event can be identified as it has a unique query parameter of
as well as a signature query parameter that will be used to verify the request. Pass these values to the
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.
|clear:||string De-orbit request package
|signature:||string Used to validate that the logout request came from LaunchKey
user_hash string that uniquely identifies the user allowing for log out.
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
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.
Create/Link A Directory User
If you have a Service that belongs to a directory, the LaunchKey SDK provides a way to add users and link devices
for users of that directory.
You use the same command to create a end-user or to link a new device with an existing end-user.
|identifier:||string Permanent and unique identifier of this user within your service. This identifier will be
used to authenticate the user as well as link additional devices to the user's account within your directory.
Dict containing the following attributes:
|qrcode:||string A URL to a QR Code for linking a device automatically
|code:||string A code for linking a device manually
response = api.create_whitelabel_user("identifier")
"qrcode" : "https://dashboard.launchkey.com/qrcode/4uzggpm",
"code" : "4uzggpm"