Customers & Sessions

Nimbu.Customer represents customer accounts. It extends Nimbu.Object.

Customer sessions can use the classic customer session token flow or an OAuth2 application. For browser applications, prefer OAuth2 when possible: the SDK works with short-lived access tokens, scopes are capped by the application, and customer tokens can be cleared or invalidated without exposing a static master token in the bundle.

OAuth2 Customer Apps

Use an OAuth2 application when a browser app needs anonymous access before login and customer access after login.

await Nimbu.initialize({
  clientId: 'oauth-client-id',
  refreshToken: 'anonymous-refresh-token'
});

The refreshToken is the app's anonymous refresh token from Nimbu. The SDK exchanges it for a short-lived access token at POST /oauth2/tokens on the first API request, caches that access token, and refreshes it before expiry.

With OAuth2 initialized, Nimbu.Customer.logIn() uses the OAuth2 Resource Owner Password Credentials flow. On success, the SDK stores the customer refresh token for the active browser session, fetches /customers/me, and makes that customer current.

const customer = await Nimbu.Customer.logIn('ada@example.com', 'secret', {
  remember: true
});

Use remember: true only when the customer explicitly wants a persistent session. Without it, the OAuth2 access state is kept in browser session storage.

After app startup, validate any stored customer before rendering authenticated UI:

await Nimbu.initialize({
  clientId: 'oauth-client-id',
  refreshToken: 'anonymous-refresh-token'
});

const current = await Nimbu.Customer.validateCurrent();

if (current) {
  console.log(current.get('email'));
}

Nimbu.Customer.logOut() removes the current customer and restores the anonymous refresh token, so the app can keep making anonymous scoped requests.

OAuth2 App Settings

Configure the OAuth2 application in Nimbu with the smallest useful scope set.

For untrusted apps, customers are prompted for consent before an authorization-code flow grants access. Trusted apps skip that prompt. Existing customer access with the same scopes is also reused without asking again. Mark an app trusted only when the site owner controls and trusts the app.

Why OAuth2 Is Safer

OAuth2 does not make public browser credentials secret. It makes their permissions easier to limit and rotate.

• Access tokens are short-lived bearer tokens instead of one long-lived static token.
• Anonymous and customer scopes cap what the SDK can request.
• Customer access is customer-bound; password changes invalidate older customer OAuth2 tokens.
• Logout clears the customer refresh token and returns the SDK to anonymous access.
• Master access can stay out of public bundles.

Avoid OAuth2 setups that undo those protections: do not publish client secrets, do not use anonymous master tokens in browser apps, and do not grant write scopes the app does not need.

Create A Customer

const customer = new Nimbu.Customer({
  email: 'customer@example.com',
  firstname: 'Ada',
  lastname: 'Lovelace'
});

await customer.save();

Sign Up

const customer = await Nimbu.Customer.signUp('ada@example.com', 'secret', {
  email: 'ada@example.com',
  firstname: 'Ada',
  lastname: 'Lovelace'
});

Successful signup makes the customer current.

Log In

try {
  const customer = await Nimbu.Customer.logIn('ada@example.com', 'secret');
  console.log(customer.id);
} catch (error) {
  console.error(error.message);
}

Successful login stores the current customer session.

Current Customer

const current = Nimbu.Customer.current();

if (current && current.authenticated()) {
  console.log(current.get('email'));
}

Initialize the SDK before reading the current customer in browser or external usage:

await Nimbu.initialize(accessToken);
const current = Nimbu.Customer.current();

Become A Customer Session

Use become() when you already have a customer session token.

const customer = await Nimbu.Customer.become(sessionToken, {
  useACL: true
});

Log Out

await Nimbu.Customer.logOut();

This clears the current customer from SDK storage.

Password Reset

await Nimbu.Customer.requestPasswordReset('customer@example.com', {
  useACL: true
});

Customer Queries

const customer = await new Nimbu.Query(Nimbu.Customer)
  .equalTo('email', 'customer@example.com')
  .first();

You can query customers as a string too, but the class form returns Nimbu.Customer instances.

Roles

const customer = await new Nimbu.Query(Nimbu.Customer).get(customerId);
const role = await new Nimbu.Query(Nimbu.Role).get(roleId);

role.getCustomers().add(customer);
await role.save();