Use this SDK to interact with the LaunchKey Platform API in your Ruby application.
Before you can begin using the LaunchKey API, you need an service. If you have not created a
service yet, you can use our Getting Started Guide to create one.
Before You Begin
Install the LaunchKey Ruby library by adding this to your application's Gemfile:
And then execute:
Or install yourself as:
If you haven't already, create an service on the new app page inside your online
Dashboard to use in conjunction with this project. You'll need details from the
details page for the next section.
Create a API Object
If you're using Rails, you can run the generator:
|domain:||string Your domain with TLD
|service_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
|passphrase:||string Retrieve private key from private.key
$ rails g launchkey:install
or if using a different framework:
# Include Ruby library
LaunchKey.configure do |config|
config.domain = 'http://yourdomain.tld'
config.app_key = 1234567890
config.secret_key = 'SECRET_KEY'
config.keypair = File.read('path/to/rsa-keypair.pem')
config.passphrase = 'PRIVATE_KEY_PASSPHRASE'
Authenticating A User
To authenticate a user, use the
authorize() method with the user's LaunchKey username. If the request is
successfully sent, the JSON response will include the
auth_request token which you'll use to reference this launch
request in subsequent calls.
|username:||string Platform username, user push ID, or end-user identifier for the user
auth_request = LaunchKey.authorize('username')
"auth_request" => "dopkpq2oqhf9ej8uuud21geh6bwi9394"
Determine Status Of Auth Request
Once you've sent an auth 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
auth_response = LaunchKey.poll_request(auth_request)
"auth" => "R8p0TXubA+R4GlOXZlyIe5R+kG+6xPDMp43Y8vaIg4+3D1ZmANXYAMssM1apBo4\/1lWDaPyUYNJopgjnY2WK\/tjkeqgkvvtnSscYGY7\/W8VYjPfv3xA2ddr9YxfS0fQtxDUAyjnn+lbd7d8uziKpTcIx5DPZ1mJ1+d0UBmPbMUf4X8WO5c3sorX"
"user_hash" => "HO38LVDKogEn4jzIOBgjOsXlDCoTDxUvmbEQDL2SAFh"
Decrypt & Check Response
When the user responds, decrypt the
auth package using the
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 application or consider them
|auth:||string Encrypted auth response from poll request
Example Decrypted Response
"device_id" => "95f5",
"response" => "true",
"auth_request" => "uew83ququ1xam6bjr1xvclvef79x6zgn",
"app_pins" => "4550,3212,7723,8488,7701"
When A User Logs Out
If a user logs out from within your website or app, you should inform our API so we can take your service profile out of
the user's Authorization List.
|auth_request:||string Request-specific token
Create/Link A Directory User
If you have an service that belongs to a directory, the 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
authenticate the user as well as link devices to the user's account within your directory.
The response will be a hash containing
qrcode, a URL to a QR Code that will be used to link a device automatically,
code, a code to link a device manually.
"qrcode" => "https://dashboard.launchkey.com/qrcode/4uzggpm",
"code" => "4uzggpm"