Skip to content

Creating app switch URLs

In rare cases you may need to programmatically create an app switch URL from an existing key. In those cases, you need to hand-craft the URL in the following format:<key ID>&r=<return URL>&n=<partner ID>&s=<HMAC>

Example URL:

Tapping the URL on an iPhone or Android phone will bring up the Unloc Work app and make the key available for use. Dismissing the key screen in the Unloc Work app will bring the user back to the originating app, via the return URL.


The simplest way to create app switch URLs is to use the returnUrl parameter when you create new keys.

The App Switch URL requires the following query parameters:

Parameter Meaning
id  The key ID
r The return URL that the Unloc app will open when the key screen is dismissed
n The partner ID
s HMAC-SHA256 signature (see below)


The URL is authenticated with an HMAC-SHA256 signature. The signature is produced with the partner's HMAC secret.

The HMAC is generated from the query parameters as follows:

HMAC_SHA256(hmacSecret, "id=<Key ID>&r=<return URL>&n=<partner ID>")


Partners receive their HMAC secret when they sign up with Unloc.

Examples on how to implement the HMAC signature in Node and Ruby:

// node.js example
// generate app switch url with hmac signature

const crypto = require('crypto');
const hmacSecret = 'secret-123';
const hmac = crypto.createHmac('sha256', hmacSecret);
const returnUrl = 'myapp://';
const partnerId = 'partner-x';

const keyId = '117ec32d-5ac3-422b-82de-cbb64540bffd';

function appSwitchUrl(keyId) {
    const params = `id=${keyId}&r=${returnUrl}&n=${partnerId}`;
    const s = hmac.digest('hex');
    return `${params}&s=${s}`;
# ruby example
# generate app switch url with hmac signature

require 'openssl'

def app_switch_url(key_id)
    hmac_secret = 'secret-123'
    return_url = 'myapp://'
    partner_id = 'partner-x'
    params = "id=#{key_id}&r=#{return_url}&n=#{partner_id}"
    s = OpenSSL::HMAC.hexdigest('SHA256', hmac_secret, params)
    return "{params}&s=#{s}"

key_id = '117ec32d-5ac3-422b-82de-cbb64540bffd'
print app_switch_url(key_id)