User Authentication API

Before retrieving user data or updating settings via the Vivoldi REST API, obtain an access token for secure authentication.

A time-limited token-based authentication mechanism strengthens account security and protects API requests from external threats.

Include the issued token in the X-Access-Token header to securely call the API.

This API is available on the Personal plan or higher.

POST

/api/user/v1/auth 

{
    "eml": "your@gmail.com"
}

Request Parameters

eml string
Email.
Used to query or update information of users added within an organization under the Business plan or higher.
Ignored in Personal and Premium plans. 
{
    "code": 0,
    "message": "",
    "result": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Parameters

code integer
Response code: 0 = Success, other values = Error
message string
Response message. If the response code is not 0, an error message is returned.
result string
When requesting to view or update user information, you must include it in the HTTP header under X-Access-Token.
The token is valid for 1 minute and must be reissued (by calling this API again) after it expires.

Why Is an Authentication Token Required?

All API requests must be authenticated to verify user identity and permissions.

This API serves the following purposes:

  • Identify the API caller
  • Validate user permissions
  • Block unauthorized requests
  • Manage secure session state

When to Use This API

<p> This API must be called before accessing any account-related endpoints, such as <a href="/url/api/user/retrieve">Retrieve User</a> or <a href="/url/api/user/update">Update User</a>. </p> <p> The issued token must be included in the HTTP header as <code>X-Access-Token</code> for all subsequent requests. Its short expiration time minimizes long-lived session exposure and helps maintain security. </p>

What a 1-Minute Token Validity Means

A 1-minute expiration is a security-first design.
Even if a token is compromised, it expires automatically within one minute, minimizing risk.

The recommended implementation is to issue the token immediately before an API call and use it right away.
Storing tokens for reuse can lead to authentication errors.

Targeting Users & Plan Requirements

On the Business plan or higher, organization admins can authenticate on behalf of a specific user by passing the user’s email in the eml parameter.

This enables automated workflows for retrieving and managing user data across the organization.
This API is available only on accounts with the Personal plan or higher, so verify your plan before use.

Things to consider

  • Store tokens securely and ensure they are never exposed externally
  • Avoid exposing tokens in client-side code, as this introduces security risks
  • Implement automatic token refresh logic when tokens expire
  • Use the API only over HTTPS