Get started with Cosmo

If at any point you need assistance, please do not hesitate to contact us. Our team is always happy to help.

Introduction

Integrating with the Cosmo ecosystem is only a few steps away. Let's start out by acquiring API keys, which you can access by signing up on the self-service Dashboard.

There are two Cosmo environments, Sandbox and Production. You'll have two different sets of API keys, one for each environment. In this tutorial, we will get started with the Sandbox environment. Navigate to the API Keys section of the Dashboard to find your Client Id and Environment Secrets.

API Key

	client_id	Unique identifier for your organization
	sandbox_key	Private key to use with sandbox environment
	production_key	Private key to use with production environment

If at any point you need assistance, please do not hesitate to contact us. Our team is always happy to help.

Integration

Once you have your API keys, it's time to integrate with Cosmo! The instructions below will guide you through the process of integration with 3 simple steps.

The Cosmo widget runs inside web or mobile apps and is launched within an iFrame. The URL that the widget runs from looks like this: https://widget.cosmopoints.com/<secure-url>

The <secure-url> can be acquired from the next step (Deploy Handshaking Endpoint). Here's a sample frontend code to deploy the widget in your frontend:

The can be acquired from the next step (Deploy Handshaking Endpoint). Here's a sample frontend code to deploy the widget in your app:

Deploying the widget on your website:Copy

Handshaking Endpoint

In order to provide a secure end to end communication between you and Cosmo APIs, we require partners to deploy a handshaking endpoint to generate a secure and unique session token every time the widget is launched. This allows Cosmo to securely identify the business partner app and the user that is logged in.

Start by installing the cosmo-sdk library to make things easier:

Install our SDK using npm:Copy

Then import the cosmo-sdk like the following:

Import CosmoSdk in your project:Copy

Then, instantiate the client by providing the clientId and clientSecret

Instantiate the CosmoSdk client:Copy

Note: You can obtain your clientId and clientSecret from the Cosmo Dashboard in the Developers section.

Generate a session token:Copy

Debit/Credit Webhook

Lastly, Cosmo requires one additional endpoint to debit or credit user accounts after converting points in or out. This endpoint will be called from the Cosmo backend every time a point conversion happens between your program and other partners in the ecosystem. It must adhere to the following specification:

You should attempt to lock access to this endpoint to the Cosmo servers which are provided to you in the dashboard.
Whether accessed is locked to Cosmo or not, the next and last step is necessary to guarantee request authenticity and fidelity.
When receiving a request to this endpoint, you must look for the X-COSMO-SIGNATURE in the header and verify that with your secret generated in the dashboard.

Verifying webhook signature:Copy

Next Steps

Congratulations, you have completed the Cosmo widget integration guide. Now your users may access the open-standard Cosmo ecosystem to loyalty partners. We ask our partners to ensure the security and performance of communication with Cosmo We're here to help you, just a click away!