Signed Identity

Signed Identity is a more secure way to provide contact identifiers. When the user logs in on your website or mobile app, your backend server will return a signed payload containing the identifiers for this user. This signed payload is called SignedIdentity. Take a look at the following sequence diagram:

Identify Contact with Signed Identity

After the signed identity is retrieved, your web or mobile application can use it to identify the contact as follows:

Android (Kotlin)

// Call backend server for user login
val response = userLogin()

// and get signed identity
val signedIdentity = response.signedIdentity

bird.contact.identify( SignedIdentity(signedIdentity) )

iOS (Swift)

// Coming soon...

Web (Js)

// Coming soon...

Generate Signed Identity

The backend server can generate a signed identity for a user as follows:

• Get the signing key and issuer from the application settings in the Bird dashboard (Developer > Applications > (your application) > Overview tab).

• Sign the user identifiers payload using the signing key.

Here is a sample code to get you started:

Node.js

const crypto = require('crypto');

let host = "https://api.bird.com";
let accessKey = "<your-access-key>";
let workspaceId = "<your-workspace-id>";
let applicationId = "<your-application-id>";
let issuer = "<your-app-signing-key-issuer>";
let signingKey = "<your-app-signing-key>";

async function onUserLogin() {
    // Authenticate the user in your system
    
    // Make SignedIdentity with a list of identifiers for this user
    let identifiers = [
        {
            key: "emailaddress",
            value: "[e-mail]",
        }
    ]
    let signedIdentity = await makeSignedIdentity(identifiers);

    // Include signedIdentity in the response to the login operation.
}

async function makeSignedIdentity(identifiers) {
    let header = JSON.stringify({
        "alg": "HS256",
        "typ": "JWT",
        "kid": issuer,
    });
    let payload = JSON.stringify({
        identifiers: identifiers
    });
    let headerBase64 = Buffer.from(header).toString('base64url');
    let payloadBase64 = Buffer.from(payload).toString('base64url');
    let signature = crypto.createHmac('sha256', signingKey).update(headerBase64 + "." + payloadBase64).digest('base64url');
    let signedIdentity = headerBase64 + "." + payloadBase64 + "." + signature;
    return signedIdentity;
}