Auth and account

These endpoints read the panel's metadata, sign in and out, describe the current account, and change your own password, second factor, signed-in browsers and API tokens. Most are for the browser session; a token has no session and no CSRF value.

Times are Unix seconds. Token requests use Authorization: Bearer, need no CSRF header, and cannot call the session-only endpoints. A browser signs in with a cookie and sends X-CSRF-Token on every write.

Panel metadata

GET/api/metapermissionpublic

Returns the panel name, version, default language and sign-in options for the sign-in page.

curl -sS "$BASE/meta"

{
  "version": "0.9.9-beta.6",
  "updatePending": false,
  "locale": "en",
  "brand": "Ovira",
  "panelAccent": "lime"
}

The OpenAPI document

GET/api/openapi.jsonpermissionpublic

Returns this OpenAPI 3.1 document, with the running version in info.version.

curl -sS "$BASE/openapi.json"

Sign in

POST/api/auth/loginpermissionpublic

Signs a browser in and sets the session cookie. With two-factor sign-in on, the answer is a challenge instead of a session.

Field	Type	Required	Meaning
username	string	yes	Account username.
password	string	yes	Account password.
remember	boolean	no	Keep the browser signed in for 30 days instead of the idle timeout.

curl -sS -c cookies.txt -X POST "$BASE/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"owner","password":"your-password","remember":false}'

{
  "admin": { "id": 1, "username": "owner", "role": "owner" },
  "csrf": "csrf-value",
  "roleName": "Owner",
  "perms": { "clients.view": "all" }
}

Without a second factor, the answer is the Me object and the cookie. With one, the answer is:

{ "mfa": true, "ticket": "ticket-value", "remember": false }

401 means a wrong username or password. 403 means the account is blocked or the licence refuses it. 429 means too many failed attempts.

Finish two-factor sign-in

POST/api/auth/mfapermissionpublic

Finishes sign-in with a TOTP code or a recovery code.

Field	Type	Required	Meaning
ticket	string	yes	The ticket from auth/login. It lasts five minutes.
code	string	yes	A TOTP code or one recovery code.
remember	boolean	no	Keep the browser signed in for 30 days.

curl -sS -c cookies.txt -X POST "$BASE/auth/mfa" \
  -H "Content-Type: application/json" \
  -d '{"ticket":"ticket-value","code":"123456"}'

The answer is the Me object and the session cookie. 401 means the code did not work or the ticket expired.

Sign out

POST/api/auth/logoutpermissionanysession only

Signs the browser out and clears the cookie. Session only.

curl -sS -b cookies.txt -X POST "$BASE/auth/logout" \
  -H "X-CSRF-Token: $CSRF"

{ "ok": true }

Who am I

GET/api/auth/mepermissionany

Returns the account behind the request, its role, effective permissions and limits, its plan, and the token when the request used one. For a browser, csrf holds the token to send on writes; for a token request it is empty.

curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" "$BASE/auth/me"

401 means no valid session or token.

My traffic pool

GET/api/auth/usagepermissionany

Returns the account's own current traffic pool. An owner always reads 0 for the limit and the end date.

curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" "$BASE/auth/usage"

{
  "usedBytes": 82463372083,
  "trafficLimit": 1099511627776,
  "expireAt": 1796000000
}

Change my password

POST/api/account/passwordpermissionanysession only

Session only. Changes your password and signs out your other browsers.

Field	Type	Required	Meaning
current	string	yes	The password in use now.
new	string	yes	The new password, checked for strength.

curl -sS -b cookies.txt -X POST "$BASE/account/password" \
  -H "Content-Type: application/json" -H "X-CSRF-Token: $CSRF" \
  -d '{"current":"old-password","new":"a-new-long-password"}'

{ "ok": true }

400 means the current password is wrong or the new one is not acceptable.

Two-factor sign-in

All of these are session-only.

POST/api/account/2fa/setuppermissionanysession only

Starts setup and returns the pending secret, its otpauth:// URI and a PNG data URL for a QR code.

curl -sS -b cookies.txt -X POST "$BASE/account/2fa/setup" \
  -H "X-CSRF-Token: $CSRF"

{
  "secret": "JBSWY3DPEHPK3PXP",
  "uri": "otpauth://totp/Ovira:owner?secret=...",
  "qr": "data:image/png;base64,..."
}

400 means two-factor sign-in is already on.

POST/api/account/2fa/enablepermissionanysession only

Turns the second factor on. The body has one required field, code, from the authenticator app. The answer holds ten recovery codes, shown once.

curl -sS -b cookies.txt -X POST "$BASE/account/2fa/enable" \
  -H "Content-Type: application/json" -H "X-CSRF-Token: $CSRF" \
  -d '{"code":"123456"}'

{ "recoveryCodes": ["abcd-efgh", "ijkl-mnop"] }

400 means setup was not started or the code did not match.

POST/api/account/2fa/disablepermissionanysession only

Turns the second factor off. The body has one required field, password.

curl -sS -b cookies.txt -X POST "$BASE/account/2fa/disable" \
  -H "Content-Type: application/json" -H "X-CSRF-Token: $CSRF" \
  -d '{"password":"your-password"}'

{ "ok": true }

400 means the password is wrong.

POST/api/account/2fa/recoverypermissionanysession only

Replaces the recovery codes. The body has one required field, password. The answer holds the new codes, shown once.

curl -sS -b cookies.txt -X POST "$BASE/account/2fa/recovery" \
  -H "Content-Type: application/json" -H "X-CSRF-Token: $CSRF" \
  -d '{"password":"your-password"}'

400 means two-factor sign-in is off or the password is wrong.

Signed-in browsers

GET/api/account/sessionspermissionanysession only

Lists your sessions, newest activity first, with the current one marked. Session only.

curl -sS -b cookies.txt "$BASE/account/sessions"

[
  {
    "id": "9f3a...",
    "createdAt": 1795800000,
    "expiresAt": 1796000000,
    "lastSeenAt": 1795919000,
    "ip": "203.0.113.9",
    "userAgent": "Mozilla/5.0 ...",
    "current": true,
    "ref": "9f3a2b7c8d1e4f60"
  }
]

DELETE/api/account/sessions/{id}permissionanysession only

Signs one browser out. Path parameter id is the session ref, or its id with at least 16 characters. Session only.

curl -sS -b cookies.txt -X DELETE "$BASE/account/sessions/9f3a2b7c8d1e4f60" \
  -H "X-CSRF-Token: $CSRF"

{ "ok": true }

404 means no such session.

POST/api/account/sessions/revoke-otherspermissionanysession only

Signs out every browser except this one. Session only.

curl -sS -b cookies.txt -X POST "$BASE/account/sessions/revoke-others" \
  -H "X-CSRF-Token: $CSRF"

{ "ok": true }

API tokens

These are session-only and are described in full on API tokens.

GET/api/account/tokenspermissionanysession only

List your tokens.

POST/api/account/tokenspermissionanysession only

Create a token.

DELETE/api/account/tokens/{id}permissionanysession only

Revoke one of your tokens.

GET/api/admins/{id}/tokenspermissionownersession only

Owner only. List one account's tokens.

DELETE/api/admins/{id}/tokens/{tid}permissionownersession only

Owner only. Revoke one token of one account.

Related pages

• API tokens: creating, scoping and revoking a token.
• Panel accounts: the account page, password and second factor.
• API overview: token errors and the session-only list.
• Settings: where My account sits.