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 (string, optional): Determines widget state after initialization, options are 'closed' | 'open' | 'hidden'. 'open' immediately opens the widget modal after initialization if the user is not logged in, 'hidden' completely hides the widget from the page (default: closed)
• 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")
• query (object, optional): Values appended as URL query parameters. Endpoints that read anonymized profile data require a purpose field here. The value must be one of Purpose values and allowed for your client in the user’s access settings.
• body (object, optional): Request body for POST/PUT requests
• headers (object, optional): Additional HTTP headers

Example (read profile with a declared purpose):

await client.fetch({
    path: '/storage/profile',
    method: 'get',
    query: { purpose: 'personalisation' },
});

Purpose values

Pick the value that matches how you use the data returned for this call, and set it as query.purpose on client.fetch(). The storage API enforces access per purpose.

Returns: Promise<any>

Server-side and backend use

client.fetch() is implemented for the browser bundle and depends on an active OIDC session managed by the Upod client in the page (for example after handleCallbackIfNeeded() and a successful login). It is not something you can call from a server runtime such as PHP, Node without the browser flow, or a server-side proxy that only forwards HTTP requests: those environments do not have the same session context as the user’s browser.

Recommended pattern when a backend needs profile context use the fetch-then-forward approach:

1. Fetch in the browser — After the user is authenticated, call client.fetch() for /storage/profile (or your integration’s equivalent) with query: { purpose: "…" } in client-side JavaScript.
2. Send only what the backend needs — POST the anonymized fields (or derived, purpose-limited labels) from the browser to your own API endpoint. Your server then uses that payload as context; it does not call client.fetch() itself.
3. Align with privacy and purpose — Keep payloads minimal, respect the purpose you pass in query to client.fetch() (see Purpose values), and treat the data as session-scoped rather than long-lived PII.

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
6. Need profile data on a backend (PHP, APIs, LLM context)? Fetch with client.fetch() in the browser, then pass anonymized data to your server — see Server-side and backend use