Authentication & sessions

How Yurbi sessions work: obtaining a token, how long it lasts, and how to design an integration around one session per user.

Every Yurbi API call except GetInstallationID requires a session token, sent as a field in the request body.

Getting a token

DoLogin exchanges credentials for a token:

curl -X POST "https://your-yurbi-server.com/api/login/DoLogin" \
  -H "Content-Type: application/json" \
  -d '{ "bolForceLogin": true, "isGuest": false,
        "UserId": "apiuser", "UserPassword": "YOUR_PASSWORD" }'

The token is in LoginSession.SessionToken, and LoginSession.SessionExpir gives the moment it lapses. Call this from your server so credentials never reach a browser.

The response also describes the signed-in user: their groups, their application roles, and the instance's licensed features. It is around 200 KB, because it includes the interface phrase table.

One session per user

Yurbi maintains a single session per user account. Each successful login issues a new token and ends that user's previous session. A token from an earlier login stops working and returns ErrorCode 101.

This shapes how an integration should be built:

• Cache the token on your server and reuse it across requests, rather than calling DoLogin per request.
• Give each integration its own Yurbi user. A scheduled export, an embedded dashboard and an interactive application should not share one account.
• When embedding for end users, create a Yurbi user per end user. Sharing one account across several people means each new sign-in ends the previous person's session.

Session lifetime

A session lasts for the instance's SESSION_TIMEOUT, which is 20 minutes by default and readable through GetAppSettings.

The window is a rolling one: every authenticated call moves the expiry forward to the time of the call plus the timeout. An integration that makes regular requests keeps its own session alive.

Two endpoints manage the session explicitly:

• CheckSession reports whether a token is still valid. ErrorCode 0 means valid; ErrorCode 101 means expired or unknown.
• RefreshSession extends a session without performing any other work — useful for a dashboard left open with no traffic.

DoLogout ends a session immediately. Call it when a short-lived script finishes.

Handling expiry

An expired token shows up in one of two ways: a 204 response with an empty body, or ErrorCode 101. Handle both by logging in again and retrying.

if response is empty (204) or ErrorCode == 101:
    token = DoLogin(...)          # replaces any earlier session
    retry the request once

Because a fresh login ends the user's previous session, a retry loop should be per-account rather than per-request: two workers sharing an account will repeatedly evict each other.

Permissions

The built-in admin account is a super-admin and bypasses application and group permissions. Any other administrator must be granted a role on each application it uses and added to the groups whose content it needs. See Permissions and the super-admin account for what to grant a service account.

Guest sessions

Set isGuest true to create a guest session for anonymous content. Guest sessions are also returned by DoLogin, and LoginSession.isGuestSession identifies them. For public content with no sign-in at all, enable anonymous view on the item and use the public view URL instead — see Embed dashboards & reports.

Reserved accounts

The scheduler and yurbi accounts are reserved for internal services and cannot sign in through the API.