How to Build User Authentication and Account Management in a Headless Architecture

Almost every developer has implemented an authentication system at least once: login forms, OAuth providers, user profiles, roles, and session management. While at first glance this may seem like a small piece of functionality, in practice it quickly turns into a separate subsystem of the application. As the product evolves, the requirements for this part of the system continue to grow.

There is a need to support social logins, implement registration via email and password, store user profile data, manage access through roles, and ensure secure handling of tokens and sessions.

In traditional architectures, all of this logic is usually implemented inside the backend application. However, when using a headless approach, authentication becomes part of the platform infrastructure rather than a separate module inside the application. This allows responsibilities to be separated: the frontend remains responsible for the interface and user experience, while the backend platform manages user identification, access rights, and security.

In this article, we will examine how to implement a user account system based on OneEntry, a backend platform built on the principles of headless architecture and cover:

• connecting OAuth providers (Google, GitHub, etc.)
• configuring authentication in the platform admin panel
• implementing login via SDK
• managing user profiles and custom attributes
• configuring roles and access permissions
• ensuring secure handling of user sessions

Configuring Authentication Providers in OneEntry

Once the authentication architecture has been defined, the next step is to configure the login mechanisms in the system. In the headless approach, this configuration is performed not in the application code but at the backend platform level.

In OneEntry, authentication management is handled through the administrative panel. Here you can define which login methods will be available to users, for example login via OAuth providers or local authentication using email and password.

Each such mechanism is implemented through an authentication provider — a separate configuration that defines the method of user authentication and the parameters of interaction with the system.

Creating and configuring a provider is done in the Users → Authentication Providers section of the administrative panel. Below is an example of creating and configuring an authentication provider in the OneEntry interface.

Video: Creating an authentication provider

Video: Editing an authentication provider

Connecting a Third-Party Provider (Google OAuth Example)

One of the most common authentication methods in modern applications is logging in through third-party services such as Google, GitHub, or other OAuth providers. This approach allows users to quickly authenticate without the need to create a separate account.

To use Google OAuth, you must first create an OAuth client in the Google Cloud Console. In the settings, you specify the redirect address to which the user will be returned after successful authentication.

For example: https://your-app.com/oauth/callback

After creating the client, Google provides two key parameters: Client ID and Client Secret. These values are used to configure the authentication provider on the platform side.

Documentation: https://doc.oneentry.cloud/docs/users/examples/google

After obtaining the OAuth client parameters, the provider is added in the OneEntry administrative panel. In the Authentication Providers section, a new OAuth provider is created where the Client ID, Client Secret, and redirect address are specified.

Once the provider is activated, the platform begins handling the entire OAuth process: redirecting the user to the provider, receiving the authorization code, and exchanging it for a token.

Implementing Login via SDK

After configuring the provider at the platform level, authentication can be integrated into the application using the OneEntry JavaScript SDK.

First, install the SDK:

npm install oneentry

Next, you need to initialize the connection to the project:

import { defineOneEntry } from "oneentry";

const { AuthProvider, Users } = defineOneEntry('your-project-url', {
  token: 'your-api-token',
});

Starting OAuth Authentication

After the user completes authentication with the external provider, the application receives an authorization code, which must be passed to the platform.

const body = {
  code: "...",
  redirect_uri: "http://localhost:3000"
};

const response = await AuthProvider.oauth('marker_auth_provider', body);

The platform exchanges the code for a token and creates a user session. After that, the user is returned to the application.

Retrieving the Current User

After successful authentication, user data can be retrieved through the SDK:

const user = await Users.getUser(langCode);
console.log(user);

SDK Documentation:

https://js-sdk.oneentry.cloud/docs/category/authprovider
https://js-sdk.oneentry.cloud/docs/users/

Local Authentication (Email / Password)

In addition to OAuth providers, the platform also supports traditional login scenarios using email and password.

This can be useful in cases where the application requires separate user registration.

const { AuthProvider } = defineOneEntry(PROJECT_URL, {
  token: APP_TOKEN,
});

const body = {
  authData: [
    {
      marker: "login",
      value: "[e-mail]"
    },
    {
      marker: "password",
      value: "12345"
    }
  ]
};

const response = await AuthProvider.auth('email', body);

Documentation: https://js-sdk.oneentry.cloud/docs/auth-provider/auth

User Profile Management

After authentication, the application gains access to user data and can work with the user’s profile.

For example, retrieving the current user data:

const profile = await auth.getCurrentUser();

Updating profile data is performed using the updateUser method:

const body = {
  formIdentifier: "reg",
  authData: [
    {
      marker: "password",
      value: "yourPassword"
    }
  ],
  formData: [
    {
      marker: "last_name",
      type: "string",
      value: "Username"
    }
  ],
  notificationData: {
    email: "[e-mail]",
    phonePush: ["[phone]"],
    phoneSMS: "[phone]"
  },
  state: {}
};

const response = await Users.updateUser(body);

Documentation: https://js-sdk.oneentry.cloud/docs/users/updateUser

Extending the User Model

The structure of the user profile in OneEntry is not fixed. It can be extended directly from the administrative panel.

In the User Attributes section, additional fields can be added, for example: avatar, phone number, date of birth, or any other profile attributes. Each field can have its own data type and validation rules. This makes it possible to extend the user model without modifying backend code.

Role-Based Access Control (RBAC)

Many applications require restricting access to different parts of the system. A simple role check may look like this:

const user = await auth.getCurrentUser();

if (user.role !== "admin") {
  throw new Error("Access denied");
}

Roles and access permissions are configured in the platform’s administrative panel. Below is an example of configuring roles and access permissions in the OneEntry interface.

Video: Configuring roles and permissions

Documentation: https://doc.oneentry.cloud/docs/users/permissions

Logout and Session Management

Ending a user session is performed through the SDK:

AuthProvider.logout('marker_auth_provider', 'token');

Token refresh and session lifecycle management are handled automatically by the platform when the SDK is configured correctly.

Conclusion

In this article, we schematically showed how our team implemented the authentication and user account system within the platform. Our goal when designing this architecture was to solve a typical problem that teams face as digital products evolve — the increasing complexity and fragmentation of the logic for managing users, roles, and sessions within the application.

In most projects, user, role, and session management gradually turns into a complex set of disconnected solutions that have to be maintained alongside the application. In OneEntry, this functionality is moved to the platform level, allowing developers to focus on product logic and the user interface.

For businesses, this approach results in a more stable application architecture. The user account system and user management become not a separate module within the project, but part of the platform infrastructure that can grow and scale together with the product.

We hope this article was helpful and helped clarify the approach to implementing authentication and user account systems in a headless architecture. We will be glad to hear your questions and feedback.