Authentication Flow

SDK Initialization

When working with the Lune SDK, we need an access token in order to initialize the SDK and render financial visualizations.

The process is:

1. Sign in with username + password → get a user key
2. Use that user key to generate tokens (access + refresh)
3. Use the access token to initialize the SDK
4. When the access token expires (Refresh Token Call Back) → use the refresh token API call to get a new one then return it in the setRefreshTokenCallback()

Step 1: Sign In

We need the accessToken to initialize the SDK, but before that we must sign in with the username + password. At the response of sign in, we get a key. That key is then used in the next step (Generate Token) inside the Authorization header.

Endpoint: POST {baseURL}/v1/user/signin

Headers:

{
  "Content-Type": "application/json"
}

Body:

{
  "username": "your_username",
  "password": "your_password"
}

Response (example):

{
  "key": "USER_KEY_12345",
  "status": "success"
}

---

Step 2: Generate SDK Tokens

Now that we have the user key from the previous step, we use it in the Authorization header to generate the SDK tokens. The response gives us an access and refresh token.

• access → used in SDK initialization
• refresh → used later to get a new access token when it expires

Endpoint: POST {baseURL}/v2/sdk/tokens/

Headers:

{
  "Content-Type": "application/json",
  "Authorization": "Token USER_KEY_12345"
}

Body:

{
  "customer_id": "CUSTOMER_ID_001"
}

Response (example):

{
  "access": "ACCESS_TOKEN_ABC123",
  "refresh": "REFRESH_TOKEN_DEF456",
  "status": "Token generated"
}

---

Step 3: SDK Initialization

With the accessToken from step 2, we can now initialize the Lune SDK. This token is required for all SDK components (cashflow, spend, budget, etc.).

After obtaining tokens:

final lunePlugin = Lune(
  baseUrl: config.baseURL,
  accessToken: authResult.accessToken!,
);
await lunePlugin.initialize();

---

Step 4: Implement the Refresh Token Callback

Since the accessToken will eventually expire, we must use the refreshToken (from Step 2) to request a new accessToken. This ensures the SDK continues working without forcing the user to log in again.

How the refresh works

The Lune SDK monitors the lifetime of the accessToken. When the token expires, the SDK automatically triggers your registered callback lunePlugin.setRefreshTokenCallback().

Inside this callback, you must:

1. Call the Refresh Token API (see Step 5)
2. Pass the refreshToken in the request body
3. Parse the response and extract the new accessToken
4. Return that accessToken to the SDK

Implementation

Set up the refresh callback:

await lunePlugin.setRefreshTokenCallback(() async {
  // 1. Call the Refresh Token API with the refreshToken
  // 2. Parse the response
  // 3. Return the new access token back to the SDK
  return newAccessToken;
});

---

Step 5: Refresh Token API

Endpoint: POST {baseURL}/v2/sdk/tokens/refresh/

Headers:

{
  "Content-Type": "application/json"
}

Body:

{
  "refresh": "REFRESH_TOKEN_DEF456"
}

Response (example):

{
  "access": "NEW_ACCESS_TOKEN_789",
  "refresh": "REFRESH_TOKEN_DEF456"
}

---

Step 6: Rendering Lune Views

After we’ve successfully initialized the Lune SDK with a valid accessToken, we can start rendering the financial visualizations inside our Flutter widget tree. This is where the SDK gives you interactive charts and dashboards such as:

• Spending patterns
• Budget tracking
• Cashflow overview

Each visualization is identified by a viewType string, such as "spend", "budget", or "cashflow".

Default Rendering

If you want to embed a view inside your existing UI, you simply call getView():

// Get a view with default settings
final view = lunePlugin.getView(viewType);

// Or get a view with custom settings
final view = lunePlugin.getView(
  viewType,
  solo: true, // Whether to render the view independently
);

This attaches the cashflow view into your Flutter widget tree, and it will automatically respect your app’s layout, navigation, and design.