AuthService

@blobs/sdk v0.1.0

---

@blobs/sdk / services / AuthService

Defined in: services/AuthService.ts:30

Handles authentication and session lifecycle operations against the Blobs auth service. Owns login, registration, token refresh, password reset, and SSO flows, plus username/email availability checks. Successful auth responses are cached under the auth namespace and propagate cache invalidations across user/blob namespaces on logout.

SSO is owned by the parent BlobsInstance (one SSOManager per SDK instance, stored on ctx.sso). AuthService is a thin forwarder to that singleton.

Example

const sdk = createSDK({ networks: [{ name: 'global', host: 'https://api.example.com' }] });
const result = await sdk.auth.login({ email: '[email protected]', password: 'secret' });
if (result.success) console.log(result.data.access_token);

Constructors

Constructor

new AuthService(context): AuthService

Defined in: services/AuthService.ts:38

Constructs an AuthService bound to the given context.

Parameters

context

BlobsContext

Shared BlobsContext providing transport, cache, SSO, and config.

Returns

AuthService

Methods

register()

register(data, options?): Promise<Response<AuthResponse>>

Defined in: services/AuthService.ts:91

Registers a new user account and caches the returned auth envelope as the current session.

Parameters

data

RegisterRequest

New user registration payload (email, password, profile fields).

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<AuthResponse>>

A Response containing the AuthResponse envelope with access and refresh tokens on success.

Throws

ApiError when the transport fails or the server rejects the registration.

Remarks

Mirrors the Go SDK Register method.

Example

const res = await sdk.auth.register({ email: '[email protected]', username: 'alice', password: 'secret' });

---

login()

login(data, options?): Promise<Response<AuthResponse>>

Defined in: services/AuthService.ts:129

Logs in an existing user with email/username and password and caches the resulting tokens.

Parameters

data

LoginRequest

Credentials payload (email or username plus password).

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<AuthResponse>>

A Response containing the AuthResponse with access and refresh tokens on success.

Throws

ApiError when the transport fails or credentials are rejected.

Remarks

Mirrors the Go SDK Login method.

Example

const res = await sdk.auth.login({ email: '[email protected]', password: 'secret' });
if (res.success) sdk.setAccessToken(res.data!.access_token);

---

logout()

logout(redirectUrl?, options?): Promise<Response<{ message: string; redirect_url: string; }>>

Defined in: services/AuthService.ts:159

Logs the current user out, revoking the cached refresh token on the server and clearing all auth, user, and blob caches. Optionally returns a redirect URL for post-logout navigation (e.g. SSO logout endpoints).

Parameters

redirectUrl?

string

Optional URL the server should include in its response for client-side redirect.

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<{ message: string; redirect_url: string; }>>

A Response containing a confirmation { message, redirect_url } payload.

Throws

ApiError when the transport fails.

---

refreshToken()

refreshToken(data, options?): Promise<Response<AuthResponse>>

Defined in: services/AuthService.ts:224

Exchanges a refresh token for a new access token and updates the cached session envelope.

Parameters

data

RefreshTokenRequest

Request payload containing the refresh token.

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<AuthResponse>>

A Response containing the refreshed AuthResponse envelope.

Throws

ApiError when the refresh token is invalid, expired, or revoked.

Remarks

Mirrors the Go SDK RefreshToken method.

---

forgotPassword()

forgotPassword(params, options?): Promise<Response<{ success: boolean; }>>

Defined in: services/AuthService.ts:254

Requests a password reset email for the given address. The backend always responds with { success: true } to avoid revealing whether the email is registered.

Parameters

params

Object containing the target email address.

email

string

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<{ success: boolean; }>>

A Response containing { success: true } regardless of whether the email exists.

---

resetPassword()

resetPassword(params, options?): Promise<Response<{ success: boolean; }>>

Defined in: services/AuthService.ts:279

Completes a password reset using the token delivered via email and a new password.

Parameters

params

Object containing the reset token and new password.

token

string

password

string

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<{ success: boolean; }>>

A Response containing { success: boolean } indicating whether the reset succeeded.

Throws

ApiError when the token is invalid or expired.

---

me()

me(options?): Promise<Response<User>>

Defined in: services/AuthService.ts:305

Returns the currently authenticated user, served from cache when available and fetched from /auth/me on cache miss. The fetched user is cached for cacheTTL.

Parameters

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<User>>

A Response containing the current User profile.

Throws

ApiError when the access token is missing or invalid.

Remarks

Mirrors the Go SDK Me method.

---

refresh()

refresh(data, options?): Promise<Response<AuthResponse>>

Defined in: services/AuthService.ts:338

Refreshes the access token using a refresh token.

Parameters

data

RefreshTokenRequest

Request payload containing the refresh token.

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<AuthResponse>>

A Response containing the refreshed AuthResponse envelope.

Deprecated

Use refreshToken instead. This alias is kept for backwards compatibility and will be removed in a future release.

---

sso()

sso(config?): Promise<SSOResult>

Defined in: services/AuthService.ts:365

Initiates a Single Sign-On (SSO) flow by opening a popup window for authentication and resolving with the resulting session data when the popup completes.

Parameters

config?

Partial<SSOConfig>

Optional partial SSOConfig (network, return URL, requested permissions).

Returns

Promise<SSOResult>

The SSOResult including session tokens and user profile when the flow succeeds.

Examples

// Simple usage
const result = await blobs.auth.sso();

// With configuration
const result = await blobs.auth.sso({
  network: 'global',
  returnUrl: '/dashboard',
  permissions: ['read:blobs', 'write:blobs']
});

---

checkUsername()

checkUsername(username, findUnique?, options?): Promise<Response<{ unique: boolean; username: string; }>>

Defined in: services/AuthService.ts:378

Checks whether a username is available and optionally returns a unique variant (e.g. alice -> alice2) when findUnique is true.

Parameters

username

string

Candidate username to check.

findUnique?

boolean = false

When true, the server returns the closest available variant if the input is taken.

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<{ unique: boolean; username: string; }>>

A Response containing { unique: boolean, username: string } where username is the canonical/suggested value.

---

checkEmail()

checkEmail(email, options?): Promise<Response<{ unique: boolean; }>>

Defined in: services/AuthService.ts:406

Checks whether an email address is available for registration.

Parameters

email

string

Candidate email address to check.

options?

MultiNetworkOptions

Optional network/tenant scoping options.

Returns

Promise<Response<{ unique: boolean; }>>

A Response containing { unique: boolean }.

---

getSSO()

getSSO(): SSOManager

Defined in: services/AuthService.ts:432

Returns the underlying SSOManager for advanced operations (e.g. provider-specific configuration, listening for SSO events).

Returns

SSOManager

The shared SSOManager instance owned by the parent SDK instance.