User Authentication

User authentication

To access the marketplace, home pages or listing pages, user authentication is not required. However, user authentication is required if the user wants to install the integration based on the workflow that has been configured that powers the integration.

To authenticate the end customer with APIFuse you need to send a JWT token along with the marketplace URL as shown below. Depending on whether you are using the subdomain or the custom domain you need to reference subdomin.apifuse.io or custom domain ex. marketplace.acme.com

https://<subdomain>.apifuse.io?jwt=<User JWT>

or

https://<custom domain>?jwt=<User JWT>

To send users directly to the listing page with authentication use the following URL:

https://<subdomain>.apifuse.io/listing/<listingId>?jwt=<User JWT>

You will need the following parameters to create the JWT token for user authentication. You can use any standard library to build the JWT.  You will also need to use the HMAC SHA256 algorithm to sign the JWT with your API secret.

• orgId (required)  -The unique identifier for your organization. The “ordId” is generated by APIFuse during the onboarding process. Contact integrations@apifuse.io to get your orgId
• externalId (required) – This is a unique identifier for your end customers in your system. It’s up to you what value you send for this field. We will use this field to identify and tie your end customer with our system.
• API Secret (required) – You need this parameter to sign the JWT token. It is available under the API section in the APIFuse application. You can generate and deactivate API keys and secrets as per your need (production environment, development environment or to refresh it for security purposes). You can use any one of the active API key secrets for signing the request.
• email – This is the email address of your end customer. It may not be a unique email and it’s an optional field.
• firstname – Your end customers first name. This is an optional field.
• lastname – Your end customers last name. This is an optional field
• monetizationPlan – This is the name of the monetization plan you have set up in the APIFuse monetization section.  Monetization plans help you control the number of transactions, integrations, and level of customization your end users have access to based on their price plan. This is an optional field. If it is omitted, the default plan is applied.
• connectorId – this is an optional field. The Unique Id is assigned by APIFuse for your SaaS application connector.
• connectionName – this is an optional field. This name will be used for creating a connection for your end-user
• Authentication fields – apart from the connectorId and connectionName you can send any data that is required for user authentication. For example, you can send an API key. Contact integrations@apifuse.io to get the specific field names for your connector.

Construct the JWT payload in the following format below:

{ “iat”: 1602676712, “exp”: 1602679712, “nbf”: 1602676912, “orgId”:”12345″, “user”:{ “externalId”:”id from your db”, “firstname”:”abc”, “lastname”:”abc”, “email”:”abc@test.com”, “monetizationPlan:”freemium” } “connection”:{ “connectionName”:”guid”, “connectorId”:”moosend-v1″, // can add any parameter below depending on your connector authentication. Contact integrations@apifuse.io to get the specific field names for your connector. “apikey”:”” } }

 

As you can see in the JSON example above, there are additional standard JWT fields such as iat, exp, nbf. These parameters decide the validity of the JWT token along with the signature.

• iat – epoch seconds when the JWT is created
• exp – epoch seconds when the JWT token will expire. If the JWT was sent beyond this time, the APIFuse marketplace will return a 401 unauthorized error.
• nbf – epoch seconds that instructs from when the JWT token is valid. If it is used before this time, APIFuse will return an error.

 

Once you construct the above payload, use any JWT library to create a JWT token and sign it with an API secret.

Below is the sample code snippet for creating a JWT in node.js using the jsonwebtoken module.

var token = jwt.sign( { “iat”: 1602676712, “exp”: 1602679712, “nbf”: 1602676912, “orgId”:”12345″, “user”:{ “exernalId”:”id from your db”, “firstname”:”abc”, “lastname”:”abc”, “email”:”abc@test.com”, “monetizationPlan”:”freemium” } }, secret );

IFrame Events

An Iframe produces the below events depending on user actions. You can listen for these events on your website and take necessary actions.

1. user_login_required – This event is published if the user is not logged in and tries to install a listing. You can listen to this event and redirect the user to the login page on your website.
2. user_listing_click – This event is published if the user clicks on any of the listings. You can use this event for analytics purposes.
3. listing_installation_complete – this event is published if the user completes the listing successfully.
4. listing_installation_failed – this event is published if the listing installation failed for any reason.

The event message is posted as a JSON stringified. You need to parse the message string before you use it.

Sample event data:

{ “id”: “user_login_required”, “targetUrl”: “https://<subdomain>.apifuse.io/listing/<listingId>”, “message”:”” }