Getting Started

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.

Two-factor, forced password change and disabled accounts

Instances can turn on two-factor authentication, require password changes, lock accounts after failed attempts and disable users (all off by default; see Login security & two-factor). These show up in DoLogin as follows:

State	What `DoLogin` returns	What your integration should do
User has two-factor enrolled	`ErrorCode 0`, a token, and `requiresTwoFactor: true` with `twoFactorMethod`	The session is pending: every other call with the token is refused until the user completes the code step in the Yurbi interface. Keep integration accounts out of this state.
Two-factor mode is Required and the user has not enrolled	`ErrorCode 0`, a token, and `requiresTwoFactorEnrollment: true`	Same: pending until the user enrolls in Yurbi.
Administrator set force password change	`ErrorCode 0`, a token, and `LoginUser.bforcepasschange: true`	The user must set a new password in Yurbi before using the token.
Account disabled, or temporarily locked after failed attempts	`ErrorCode 101`, the ordinary invalid-login response	Indistinguishable from a wrong password by design. Check the account with `GetContactById` (`disabled`, `lockdate`) if you hold an admin token.

A server-side integration that signs users in on their behalf controls their credentials, so the simplest approach is to keep those users on Optional two-factor mode without enrolling, or to make them EXTERNAL/SSO users, so DoLogin always returns a usable token. The guide has the details.

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.