Authentication

The connect function is used to authenticate with Smokeball and generate a token session for your application.

The token session provides access to short-lived access tokens that can be used to make API requests to the Smokeball API with the scopes you have configured in your Smokeball App.

Prerequisites

1. Initialize the SDK

Before using the connect function, you must initialize the SDK.

import { SmokeballClientSdk } from '@smokeballdev/smokeball-client-sdk';

const sdk = SmokeballClientSdk.get();
 
// Initialize
await sdk.init(); 

2. Obtain an Embed Token from your Backend

Your backend will receive an embed token from Smokeball (for example, through a plugin pre-flight request). This embed token:

• Has a lifetime of 1 minute
• Is tied to the logged-in user ID
• Is tied to your integrating app’s Client ID

Your backend should provide this token to your client application.

Using the Connect function

Only applications that have been configured and approved by Smokeball are able to use the connect function.

Once you have:

1. Initialized the SDK
2. Obtained an embed token from your backend

You can call the connect function:

const tokenSession = await sdk.auth.connect({
  token: embedToken
});

The connect function accepts a request object with the following structure:

{
  token: string  // The embed token received from your backend
}

Response

The connect function returns a token session that exposes a token() function. This token session:

• Lasts for 1 day regardless of refresh token lifetime, requiring a new session to be generated everytime your app is loaded
• Provides access to short-lived tokens scoped to your app’s Client ID and configured scopes

The token session object has the following structure:

{
  token: () => Promise<TokenResponse>;  // Function to acquire a new short-lived access token
}

Getting Access Tokens

Use the token() function from the token session to acquire a new short-lived access token:

// Get a new access token
const response = await tokenSession.token();

// Use the access token in API requests
const apiResponse = await fetch('https://api.smokeball.com/firm', {
  headers: {
    'Authorization': `Bearer ${response.access_token}`
  }
});

The refresh token and refresh functionality are handled automatically by the SDK backend. You do not need to manage refresh tokens directly.

Complete Example

import { SmokeballClientSdk } from '@smokeballdev/smokeball-client-sdk';

// Get the SDK instance
const sdk = SmokeballClientSdk.get();

// Step 1: Initialize
await sdk.init();

// Step 2: Connect using the embed token to create a token session
try {
  const tokenSession = await sdk.auth.connect({
    token: embedToken
  });
  
  // Step 3: Use the token session to get a token response
  // The token session lasts for 1 day
  const response = await tokenSession.token();
  
  console.log('Response:', response);
  
  // Use the token to make API requests
  const apiResponse = await fetch('https://api.smokeball.com/v1/endpoint', {
    headers: {
      'Authorization': `Bearer ${response.access_token}`
    }
  });
  
  // Get a new access token when needed (the SDK handles refresh automatically)
  const newResponse = await tokenSession.token();
  
} catch (error) {
  console.error('Connect failed:', error);
}

Notes

• The embed token is provided to your backend by Smokeball - typically via a secure pre-flight request, or similar integration flow. Your backend is responsible for securely receiving and passing this token to your client for SDK authentication.
• The embed token is valid for only 1 minute and can be used a single time. Be sure to use it immediately after receiving it, as it will expire quickly and cannot be reused.
• The token session created by connect lasts for exactly 1 day, after which you must generate a new session.
• Access tokens obtained via token() are short-lived and scoped to your app’s Client ID and configured scopes.