# Users

Users are critical to your platform as they usually own or Search your platform Assets and potentially generate Transactions.

Just provide a username and a password to create a User:

await stelace.users.create({
  username: 'user@example.com',
  password: 'secretPassword'

username is unique across all your users. It can be anything that makes sense to your business: an email, a phone number or a special internal ID.


password is securely salted and hashed before being saved to your database.

# Private information

Stelace trusts in privacy by design. We intentionally hide information related to User identity.

For instance, only the authorized staff members (having access to private namespace) and Users themselves will see following personal data:

  • username
  • firstname
  • lastname
  • email

Stelace provides the public property displayName that can be viewed by any other User.

# Authentication

To authenticate a User and perform actions with their account, using stelace.js:

await stelace.auth.login({
  username: 'user@example.com',
  password: 'secretPassword'


You have to use a publishable API key (pubk_...) instead of a secret one (seck_...) when dealing with user sessions, for a secret key would make user restricted permissions useless.

To destroy the current user authentication session:

await stelace.auth.logout()

# SSO & external authentication

Stelace lets you authenticate your users with external providers, from social login to Enterprise-level SSO.

# Social login

All Instant plans currently support the following OAuth2 providers:

  • github
  • google
  • facebook

All you need to do is add one of these to the private configuration of your platform, including appropriate credentials depending on the provider.

# Creating your OAuth2 app with provider

When creating your OAuth configuration with provider, here are the callback URLs you have to use:

  • Authorization callback: https://api.stelace.com/auth/sso/[xxx_test]/[provider]/callback
  • Logout callback (OpenId): https://api.stelace.com/auth/sso/[xxx_test]/[provider]/logout/callback

where [xxx_test] is a unique identifier for your platform and environment (either live or test).

Your platform identifier is available on the configuration page of your dashboard.

# Setting up social login with Stelace API

Here is how you can setup social login with github provider using stelace.js:

await stelace.config.updatePrivate({
  stelace: {
    ssoConnections: {
      github: {
        active: true,
        protocol: 'oauth2',
        // You get these when creating your Github OAuth app
        // https://github.com/settings/applications/new
        clientId: '034xxxxxxxxxxxxxxxxx',
        clientSecret: 'fb8xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        // Your users will be redirected to this URL after login
        afterAuthenticationUrl: 'https://marketplace.demo.stelace.com'


You need to use your secret key to have appropriate config:edit:all permission.

And that’s it for the backend!

You can see how this fits in our open-source marketplace template login popup.


ssoConnections configuration object can accept custom SSO configurations with an appropriate plan.

Enterprise plan is currently needed but please feel free to get in touch.