API Authentication Flow

Use this section as a guide when implementing the LaunchKey API server-side. Our API is designed around the REST model and returns JSON data. Error codes indicate the success or failure of a given API call.

API Endpoint

https://api.launchkey.com/

Resource locations

  • /v1/ping
  • /v1/auths
  • /v1/poll
  • /v1/logs

Getting started with the LaunchKey API

Before you begin

Before you can begin interacting with the LaunchKey API, you need to:

  1. Download the LaunchKey mobile app and pair your device
  2. Log in to your online dashboard and create a new developer app
  3. Generate or provide your public key, and save your private key and secret key on the app details page of your new developer app

Note: You can regenerate new keys if needed, but the previous key will be invalidated

You now have

app key Unique 10 digit application identifier
secret key application secret key, do not share
private key application private key, do not share
public key application public key, generated or provided by developer

Process Flow Guide

The diagram on the right shows the path of various authentication flow processes as data traverses between your application, the LaunchKey API, and the end user's device. This guide may be useful as you visualize your approach to integrating the LaunchKey API. Click image to enlarge

Process flow guide - click to enlarge

API Encryption Examples

Implementing this authentication flow requires encryption that must be followed carefully. To help out, we've provided encryption examples for a variety of common libraries and languages including: PyCrypto (Python), M2Crypto (Python), OpenSSL (Ruby), phpseclib (PHP), CommonCrypto (iOS), Spongy Castle (Java, Android). Reference these examples as needed when implementing the flow.

Making API Requests

In order to make API requests to everything except /ping, you will need to send some authentication information with each request.

The authentication information must include the app_key, secret_key encrypted using the API's public key, and a signature on the encrypted secret_key package using your private key.

API auth package

  • app_key
  • secret_key (encrypted with public key)
  • signature (on secret_key using private key)

Configure Library

If you're using one of our libraries to implement the LaunchKey API, ensure you include the library and properly configure it. Details like your app_key and secret_key can be obtained from your app details page within your dashboard.

CURL
PHP
PYTHON
RUBY
.NET
  • Not applicable

Ping Request

The first thing you need to do is make a request to /ping to receive your public key.

Example Request

CURL
PHP
PYTHON
RUBY
.NET
  • /* PHP library handles ping request internally */
  • /* Python library handles ping request internally */
  • /* Ruby library handles ping request internally */
  • /* .NET library handles ping request internally */

Example response

{
"date_stamp" : "2013-04-20 21:40:02",
"launchkey_time" : "2014-04-20 08:50:36",
"key" : "-----BEGIN PUBLIC KEY-----\n\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA8zQos4iDSjmUVrFUAg5G\nuhU6GehNKb8MCXFadRWiyLGjtbGZAk8fusQU0Uj9E3o0mne0SYESACkhyK+3M1Er\nbHlwYJHN0PZHtpaPWqsRmNzui8PvPmhm9QduF4KBFsWu1sBw0ibBYsLrua67F/wK\nPaagZRnUgrbRUhQuYt+53kQNH9nLkwG2aMVPxhxcLJYPzQCat6VjhHOX0bgiNt1i\nHRHU2phxBcquOW2HpGSWcpzlYgFEhPPQFAxoDUBYZI3lfRj49gBhGQi32qQ1YiWp\naFxOB8GA0Ny5SfI67u6w9Nz9Z9cBhcZBfJKdq5uRWjZWslHjBN3emTAKBpAUPNET\nnwIDAQAB\n\n-----END PUBLIC KEY-----\n"
}

The key returned from the /ping response is the public key with which you'll need to encrypt your secret key in authentication requests. The launchkey_time is the current datetime on the server which should be sent back in authentication requests.

Definition

GET https://api.launchkey.com/v1/ping

$launchkey->ping();

api.ping()

None

API Authentication

You need to construct the secret_key value before encrypting it. It should be a JSON string that contains two values: secret and stamped. An example string would look like the JSON response below.

Example JSON String

{
"secret": "SECRET_KEY",
"stamped": "2014-04-20 08:50:36"
}

Note: the response above has not been encrypted.

Once you've created the JSON string, use the key from the /ping response to RSA encrypt this string as your secret_key. For encrypting you must use PKCS1_OAEP padding and base64 encode the result.

Use your private key to RSA sign the encrypted package. Use SHA-256 to sign and base64 encode the result.

You now have all the authentication information required to make requests.

Authenticating a User

When a user wants to authenticate with your application, you'll need to send their username to LaunchKey so we can push a launch request to their paired device(s). Use the auths POST with the required authentication information in addition to the user's LaunchKey username.

Sessions vs. Transactions

Authentication requests can be designated as sessions or transactions based on the needs of your application. 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 de-orbiting (e.g. approving receipt of a package). Within the LaunchKey app, the end user will see a blue dot next to active sessions and a grey dot next to inactive transactions. Sessions are default, but transactions can be specified by setting session=0.

Example Request
CURL
PHP
PYTHON
RUBY
.NET

Example response

{
"auth_request" : "dopkpq2oqhf9ej8uuud21geh6bwi9394"
}

Definition

POST https://api.launchkey.com/v1/auths

Parameters

app_key integer

Unique 10 digit app key from your app details page in dashboard
secret_key string

App secret key from your app details page in dashboard
signature string

Signature on encrypted secret_key package using your private_key
username string

Unique LaunchKey username of user you're authenticating
session integer 1

1 to specify session auth type, 0 for transaction auth type

Checking Authentication Status

Now let's check to see if the user has authenticated yet using the auth_request you just received.

The returned string is needed for continuing as well as terminating the authorization (deorbit). After the authentication request is made, the user is responsible for either accepting or rejecting the auth request. To continue the process, you must poll until a hash containing the final auth payload is returned:

Example Request
CURL
PHP
PYTHON
RUBY
.NET

Example response

{
"successful" : false,
"status_code" : 400,
"message" : "There is no pending request",
"response" : {}
}

Definition

GET https://api.launchkey.com/v1/poll

Parameters

app_key integer

Unique 10 digit app key from your app details page in dashboard
secret_key string

App secret key from your app details page in dashboard
signature string

Signature on encrypted secret_key package using your private_key
auth_request string

The request-specific token returned from the auths POST

The user hasn't responded, let's try again:

Example Request
CURL
PHP
PYTHON
RUBY
.NET

Example response

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

Arguments

auth string

Encrypted package containing the user's response
user_hash string

The unique string you will use to identify the user in the future

Now that we've received a hashed response, we know the user has responded. Now it's time to decrypt the response.

Decrypt & Verify User's Response

Once the user has responded to the authentication request, you'll need to decrypt the response. Use your RSA private key to decrypt this package. Remember it uses PKCS1_OAEP padding.

The returned package will contain a boolean response indicating whether or not the user approved the authentication request or denied it, tokens to help ensure the response is from the user's device, and the auth_request which can be used to match which request was sent out.

Example Request
CURL
PHP
PYTHON
RUBY
.NET
  • # No cURL example, processed locally

Definition

None

Response Tokens

Every time a device responds to an authentication request it will create a 4 digit token to be sent inside the encrypted response package. Along with the new token, up to 4 of the trailing tokens generated by that device in previous authentication requests will also be included.

By storing tokens (per user) as they're created in authentication requests, you can validate with greater certainty that the request came from a legitimate user's device.

 

Update Status on User's Device

A user is considered authenticated when a decrypted response returns true and the remaining package data checks out. To update the status on the user's device you need to let LaunchKey know it was successful.

Example Request
CURL
PHP
PYTHON
RUBY
.NET
  • // Library handles this automatically when auth response is verified or deorbit is called.
  • # Library handles this automatically when auth response is verified or deorbit is called.
  • # Library handles this automatically when auth response is verified or deorbit is called.
  • # Library handles this automatically when auth response is verified or deorbit is called.

Example response

{
"message" : "Successfully updated"
}

Definition

PUT https://api.launchkey.com/v1/logs

Parameters

app_key integer

Unique 10 digit app key from your app details page in dashboard
secret_key string

App secret key from your app details page in dashboard
signature string

Signature on encrypted secret_key package using your private_key
action string Authenticate

Authenticate user
status boolean True

True if authentication was successful, False if it failed
auth_request string

Request-specific token

Keep us Informed of Logouts

If a user logs out it would be helpful to let our API know so we can take it out of their Orbit list. In order to do this, you must keep track of the auth_request value that you used to check the authentication status of the user to begin with. If you send that in along with the action set to Revoke the user will be marked as logged out in our system.

Example Request
CURL
PHP
PYTHON
RUBY
.NET

Definition

PUT https://api.launchkey.com/v1/logs

Parameters

app_key integer

Unique 10 digit app key from your app details page in dashboard
secret_key string

App secret key from your app details page in dashboard
signature string

Signature on encrypted secret_key package using your private_key
action string Revoke

Logout user
status boolean True

True if authentication was successful, False if it failed
auth_request string

Request-specific token

Handling Callbacks

Optionally, you can receive callbacks when a user authenticates for your app and when a user deorbits. Create a place where we can send those callbacks and then specify it in the Callback URL field of your app in the LaunchKey Dashboard.

When a User Authenticates

You will receive 3 parameters: auth, user_hash and auth_request. The user_hash is the identifying value for a user. If you track your users in persistent storage (e.g. a database) this will be the value you should keep to identify them in the future. This value will never change even if the user changes their LaunchKey username. The auth value is an encrypted package; the decryption is explained in the Decrypt response section. After decrypting you will receive an auth_request value as sent from the device which should match the auth_request value you received from the callback and serve as another reassurance of authenticity.

When a User De-orbits

You will receive two parameters: deorbit and signature. The deorbit parameter includes a JSON string with two variables: user_hash and launchkey_time. The user_hash is the identifying value for the user wishing to deorbit and can be used to look them up in your session or database. The launchkey_time is used as a measure to make sure the request has been made recently. For example, if the user has logged out and already logged back in to your app since the request was made, it would be safe to disregard. The launchkey_time should be compared to the launchkey_time value in the /ping call.

The second part, the signature, is used to validate that this deorbit request did in fact come from LaunchKey. You can check the signature against the deorbit data by running an RSA signature verification function using SHA256 for the digest. The data you're checking the signature on is the JSON string in the deorbit parameter.

Example Request
CURL
PHP
PYTHON
RUBY
.NET
  • No example
  • # coming soon

After the authenticity of the deorbit has been confirmed, you can keep us informed by updating the logs.

Definition

No definition

Are you ready to evolve your security beyond the password era?

Get started immediately by downloading the LaunchKey mobile app or by contacting a LaunchKey representative today.

Download Mobile App

Enterprise Sales

Contact Us