API Reference

This section contains detailed reference documentation for the Upod client library, including API methods, data formats, and configuration options.

Client Library API

upod.initialize(settings)

Initializes the Upod client library.

Parameters:

• authority (string, required): Base URL of the authentication server, e.g. "https://account.upod.eu"
• client_id (string, required): Your OIDC client ID (obtained by contacting us)
• redirect_uri (string, required): URL where users return after login
• post_logout_redirect_uri (string, required): URL where users are redirected after logout
• language (string, optional): Language code for UI elements (default: "en")
• widget (boolean, optional): Enable/disable automatic widget (default: true)
• showCookieDeclineOverlay (boolean, optional): Enable cookie decline overlay (default: false)
• cache_user_data (boolean, optional): Cache user data locally (default: true)
• cache_ttl (number, optional): Cache TTL in milliseconds (default: varies)

Returns: Client instance with methods

client.login()

Redirects the user to the Upod login page.

Returns: Promise (redirects user)

client.logout()

Logs out the current user and redirects to post_logout_redirect_uri.

Returns: Promise (redirects user)

client.isAuthenticated()

Checks if the user is currently authenticated.

Returns: Promise<boolean>

client.getUser()

Gets the current user object (if authenticated).

Returns: Promise<User | null>

client.handleCallbackIfNeeded()

Handles the OIDC callback after user authentication. Should be called on page load.

Returns: Promise<void>

client.fetch(options)

Makes an authenticated API request to the Upod storage API.

Parameters:

• path (string, required): API endpoint path (e.g., "/storage/profile")
• method (string, required): HTTP method ("get", "post", "put", "delete")
• body (object, optional): Request body for POST/PUT requests

Returns: Promise<any>

client.onLogin(callback)

Registers a callback function that is called when a user logs in.

Parameters:

• callback (function): Function to call on login, receives user object

Returns: Function to unsubscribe

client.onLogout(callback)

Registers a callback function that is called when a user logs out.

Parameters:

• callback (function): Function to call on logout

Returns: Function to unsubscribe

client.showCookieDeclineOverlay()

Shows the cookie decline overlay (if enabled in configuration).

Returns: void

client.clearAllCache()

Clears all cached user data.

Returns: void

Data Formats

Configuration Options

URLs

• Authority: https://account.upod.eu (use this for the authority parameter in upod.initialize())
• CDN: https://cdn.upod.eu/client/bundle.browser.js (include this script in your HTML)

Error Handling

The client library handles errors gracefully:

• Authentication errors: User is redirected to login if session expires
• Network errors: Errors are logged to console, callbacks receive error objects
• Invalid configuration: Errors are thrown during initialization

Best Practices

1. Always call handleCallbackIfNeeded() on page load
2. Use onLogin and onLogout callbacks to update your UI
3. Handle errors in fetch() calls with .catch()
4. Check isAuthenticated() before making API calls
5. Use appropriate cache settings based on your use case