> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smokeball.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

The [`connect` function](./api/@smokeballdev/namespaces/auth/interfaces/Api) 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.

```javascript theme={"dark"}
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

<Note>
  Your backend should provide this token to your client application.
</Note>

## 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:

```javascript theme={"dark"}
const tokenSession = await sdk.auth.connect({
  token: embedToken
});
```

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

```javascript theme={"dark"}
{
  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:

```javascript theme={"dark"}
{
  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:

```javascript theme={"dark"}
// 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}`
  }
});
```

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

### Complete Example

```javascript theme={"dark"}
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.