Overview

Depending on your marketplace's settings, buyers may find that they're required to log in more than once. For a more seamless experience, you can enable auto-sign in to allow your buyers to access marketplace offerings after signing in once (per session).

Auto Sign In is a feature available only on our Pro subscription plan.

Sign In Methods

There are 2 options for implementing auto-sign in: embedded and non-embedded. Details for both are outlined below.

Embedded Auto Sign-In

Before reading this section, please review marketplace embed - the section below exclusively describes how to obtain the auto sign-in parameters that are needed to embed your marketplace.

Creating the JWT

Obtain the secret key used to sign the JWT and your marketplace id (cid)
Create the JWT

How to obtain the secret key and cid

Log in and navigate to your marketplace's Settings page
Click on the "Embed" tab

Your security key and cid (i.e. marketplace ID) will be visible to be copied:

How to create the JWT

💡 Builtfirst uses JWT to securely authorize access and exchange information.

When building the JWT, make sure you set the following

Header:

typ : must be JWT
alg : must be HS256

{ 
 "alg": "HS256",
 "typ": "JWT"
}

Claims (all are mandatory):

user_email: email address of the user. this is our "key" to identifying whether a user exists or not
user_first_name: The first name of the user
user_last_name: The last name of the user
jti: stands for JWT ID Claim and should be unique within the span of the valid request window which is currently 3 minutes. We use this to defend against replay attacks.
iat: stands for issued at and is a "now" timestamp in seconds (not milliseconds) since epoch. Requests should be made immediately, but we currently provide a generous leeway and validate that the request is no longer than 3 minutes old.
user_external_id: the Partner's unique identifier for the user. Used for cross-referencing and debugging.
company_external_id: the Partner's unique identifier for the company associated with the user. If there is a matching company_external_id, Builtfirst will add the user to the existing Organization, otherwise, a new Organization will be created (and the user will be added to that new Organization).
company_name: the name of the user's company. Will be used if a new Organization is being created.

Example

{ 
 "user_email": "jane@company.com",
 "user_first_name": "Jane",
 "user_last_name": "Doe",
 "jti": "Xjd83dk5", 
 "iat": 1639415753, 
 "user_external_id": "123",
 "company_external_id": "456",
 "company_name": "Company Inc."
}

💡 When implementing this integration, you must ensure that the company details passed via JWT for your site's users that belong to the same organization match. This prevents errors and duplicates when trying to map users to the same organization.

Environments

Builtfirst provides 2 environments for integration:

TEST is a test environment that should be used for developing against and testing your integration prior to using the production environment.
PROD is the Builtfirst production environment with real users, accounts, data, etc.

If the TEST environment is needed please contact support to obtain the details that are required.

Example of JWT generator function written in PHP for WordPress

PHP

 function generateJwt($user, $secret, $companyExternalId, $companyName, $companyWebsite) { 
// Header
 $header = json_encode([
'typ' => 'JWT',
'alg' => 'HS256'
 ]);
 $base64UrlHeader = base64UrlEncode($header);

// Payload
 $now = time(); $common = array(
'iat' => $now,
'jti' => md5($now . rand()) 
);

 $user_attributes = array(
 'user_external_id' => $user->ID, 
 'user_email' => $user->user_email,
 'user_first_name' => $user->user_firstname, 
 'user_last_name' => $user->user_lastname, 
 'company_external_id' => get_user_meta( $user->ID, $companyExternalId, true), 
 'company_name' => get_user_meta( $user->ID, $companyName, true), 
 'company_website' => get_user_meta( $user->ID, $companyWebsite, true) 
);

 $payload = json_encode(array_merge($common, $user_attributes));
 $base64UrlPayload = base64UrlEncode($payload);

// JWT
 $message = $base64UrlHeader . "." . $base64UrlPayload;
 $signature = hash_hmac('sha256', $message, $secret, true); 
 $base64UrlSignature = base64UrlEncode($signature); 
 $jwt = $base64UrlHeader . "." . $base64UrlPayload . "." . $base64UrlSignature;
 return $jwt;
} 

 function base64UrlEncode($text) {
 return str_replace(
['+', '/', '='],
['-', '_', ''], 
 base64_encode($text) 
); 
}

NodeJs example

const jwt = require("jsonwebtoken");
const crypto = require('crypto')

function generateJwt(payload, jwtKey){
    const iat = Math.round(Date.now() / 1000)
    const jti = crypto.createHash('md5').update(iat+crypto.randomBytes(256).toString()).digest('base64')
    
    const token = jwt.sign({...payload, iat, jti}, jwtKey, {
        algorithm: "HS256",
    })
    return token
    
}

const jwtKey = ""
const payload = { 
   "user_email": "",
   "user_first_name": "",
   "user_last_name": "",
   "user_external_id": "",
   "company_external_id": "",
   "company_name": "",
   "company_website": "" 
}

console.log(generateJwt(payload, jwtKey));

Additional Resources

Non-Embedded Auto Sign-In

To automatically authenticate a user, your application must obtain an authentication code from Builtfirst, then send that user to the Builtfirst marketplace with the code in the URL.

How to obtain the authentication code

Execute a request like the one below from the backend of the partner system. Make sure the API Key used in the request is safely stored.

curl --location --request POST 'https://api.builtfirst.com//api/v3/authentication_code' \
--header 'Content-Type: application/json' \
--header 'origin: https://[marketplace url]' \
--header 'X-API-Key: [your api key]' \
--header 'X-Cid: [your marketplace id]' \
--data-raw '{
    "data": {
      "type": "authentication_code",
      "attributes": {
        "email": "[buyer user email]",
        "first_name": "[buyer user name]",
        "last_name": "[buyer user last name]",
        "user_external_id": "[id of the user in the partner system]",
        "sign_up_organization_name": "[name of the user organization]",
        "company_external_id": "id of the user organization in the partner system"
      }
    }
  }'

The response will include a code that later can be used to authenticate the user. The code can be used only once and is valid for about 3 minutes.

If the provided user doesn't yet exist when a code is requested, we will create a new user and - if applicable - an organization.

How to use the code to authenticate the user

Redirect the user to:

https://[marketplace-domain]/?code=[code]

Marketplace Embeds and Auto Sign-In/Up