User choice of Gaia hub now available during onboarding


We’re excited to announce new support for user choice of Gaia hub during onboarding.

Developers can opt to enable the functionality described below for new users who prefer to use their own Gaia hubs instead of the one provided by Blockstack PBC.

This is new and rather experimental functionality, so we’re looking for early feedback from the developer community to make it better. Please test it out and tell us what you think!

You can also try out this new functionality with our test application before integrating it yourself.

Users will need to authenticate with the browser hosted by Blockstack PBC or download the latest version of the browser (0.35.1) to their macOS, Windows or Linux devices to encounter this new functionality during onboarding once enabled by developers for the apps they use.

Note that this feature is currently available only to new users on Blockstack, not existing ones. We have yet to develop support for data migration between Gaia hubs. We plan to release support for existing users once we hub migration is possible.

Enable the Gaia hub URL option for new users

During onboarding, new users are assigned by default to a Gaia hub hosted by Blockstack PBC. This gets them started without requiring that they host and configure their own Gaia hubs.

However, a major tenet of Blockstack’s mission is to empower users to make their own choice regarding where to store their data. And we believe that most users would ultimately benefit most from storing their data outside of Blockstack PBC’s control. Users themselves – not not any developer or platform – should own and manage their app data.

As a step towards fulfilling this principle, we’re now empowering developers to enable a new prompt for users who want to provide the URL to a Gaia hub they’ve either hosted themselves or been granted permission to use by someone else.

If a developer enables this feature, new users will see this modal after entering their passwords:

The user can then choose to continue with Blockstack PBC’s default Gaia hub (indicated here as “Blockstack’s official provider”) or configure their own (by selecting “Use different provider”).

If the user chooses “Use different provider”, they’ll encounter a modal that asks them to provide the URL for the Gaia hub of their choice:

Note that the Gaia hub hosted by Blockstack PBC is located at Any user who wishes to use a different hub will need to host it at their own HTTPS address. They can also can enter the HTTPS address of a hub hosted by someone else and made available to them.

Once the user submits the above form, they will proceed as normal through the flow. But any data they generate while using apps that store data through Blockstack’s Gaia technology will be stored to their indicated hub instead of the hub hosted by Blockstack PBC.

To enable this feature as a developer, you first need to upgrade to the latest version of blockstack.js.

Then, modify your sign-in flow to apply the solicitGaiaHubUrl parameter with value true when executing the makeAuthRequest method:

import {
} from 'blockstack';

const authRequest = makeAuthRequest(
  ['store_write', 'publish_data'],
  nextHour().getTime(), {
    solicitGaiaHubUrl: true
  } // new options param


Note that by setting all of those first parameters to undefined, you’re opting to use just the default value for those arguments. See the docs for makeAuthRequest for more info.

Recommend a Gaia hub URL for new users

Are you a developer who wants to create specific funnels for users who may want to use the same Gaia hub while creating their Blockstack IDs?

We’ve also released the ability to pass a preset Gaia hub URL when sending these new users through the onboarding flow.

For example, if you have a corporate client whose employees would all like to use your application with a company-run Gaia hub, you can create a funnel that passes that company’s hosted Gaia hub URL.

Simply provide an additional recommendedGaiaHubUrl value alongside the solicitGaiaHubUrl indicated in the previous section above:

import {
} from 'blockstack';

const authRequest = makeAuthRequest(undefined, undefined, undefined, undefined, undefined, undefined, {
   solicitGaiaHubUrl: true,
  recommendedGaiaHubUrl: ''

const authRequest = makeAuthRequest(
  ['store_write', 'publish_data'],
  nextHour().getTime(), { 
    solicitGaiaHubUrl: true, //new options param
    recommendedGaiaHubUrl: '' // new options param


New users will subsequently encounter the following modal after entering their passwords:

These users can consequently choose to apply the recommended Gaia hub (whose URL is indicated in the grey area near the top), the hub hosted Blockstack PBC (indicated as “Blockstack’s provider”), or an entirely different one (“Use different provider”), leading to the same Gaia hub URL form as in the section above.

Proposal: User-selectable Gaia Hub UX

For an usual enterprise scenario, where the company policy dictates that application data be stored only in a location under the enterprise’s control, an option would be needed to make it mandatory for the user (an employee of the company) to only choose a hub that the enterprise owns. Has there been any thought around supporting such a flow?


Thanks for the comment; that’s a good question.

The above “recommended URL” approach was designed to address that enterprise scenario at least in part, in that an enterprise can send its employees through a funnel that recommends an enterprise-owned Gaia hub, though it doesn’t make that hub’s election strictly mandatory.

I suppose we could offer an additional configuration that makes it mandatory, should enterprises need greater assurance that employees choose the hub. I think we were a bit reticent to support a mandatory scenario in this release since ultimately we want to empower end-user choice. However, perhaps we can find a UX solution that balances both enterprise and user needs well here.

Do you have a particular enterprise use case in mind that we could help design around?


For an enterprise scenario, I think the initial implementation of the custom gaia hub is perfect. A user’s organization should be managing this, not Blockstack or the app. The app (as a company) can offer services to the enterprise to make sure things run a little smoother, but in the end it is up to the company to ensure their employees are taking the appropriate action and it is up to the app to make the experience as easy as possible.

Here’s how Graphite plans to tackle this for enterprise:

-New enterprise customer receives a name on the .graphite namespace
-All enterprise users for that company will receive a sponsored name in the namespace (i.e. username.companyname.graphite)
-During the on boarding process for registering the sponsored name in the .graphite namespace, there will be a custom flow that suggests the enterprise’s gaia hub. A user, could override this, but A) why would they? and B) this can still be recoverable by having the user create a new account and select the proper hub.

Some of the above steps require creating a custom authentication flow (i.e. registering names in the .graphite namespace), but the flow as a whole makes use of what Blockstack built pretty nicely, I think. And it should serve enterprises well.


I see a fundamental difference in the matter of data ownership between the individual user scenario and that for an enterprise. It makes perfect sense to provide complete ownership of the data to the user when it is a software that they use in their individual capacity. Here there are just two parties, the application software vendor and the user and it is indeed one of the primary goals of Blockstack to empower the user by giving them complete control over their data. However, in the enterprise scenario, there is an additional party, the company for which the end user works. All the data generated by the end-user in a standard enterprise application in most cases legally belongs to the company and most companies will have strict policies about where the data can reside. It is important for most enterprise scenarios that data generated by their employees do not end up in a non-standard location owning to perhaps some inadvertent incorrect choice of the Gaia server by the employee.

In the flow that I have in mind, the enterprise admin would be responsible for the creation of the Blockstack IDs for all the users through a programmatic interface for the same. I have been looking at namespaces as a means to organise user names for a enterprise, but I don’t have the complete lowdown on namespaces yet. However I recollect that there was a substantial cost to registering a namespace and that anyone could create an ID in a namespace. (Is that correct?) Any additional information / links would be highly appreciated. For access to the application, my thought was to have the enterprise admin provision the Blockstack IDs of eligible employees in the application, acting as a sort of white-list of employees who could use the application. I am trying to understand your flow better. Are you suggesting that every application have its own namespace? When you say “All enterprise users for that company will receive a sponsored name in the namespace”, does it mean than the user needs to have a unique name for each application that they use?


No, not necessarily. A user could use an id created via Graphite for any app. However, in the enterprise scenario above, I would not advise my customers to do so. I would suggest to them that they have a separate account for their organizational Graphite account. Just like today people have their work Google accounts and their personal Google accounts.

The flow you proposed is actually very much like what I’m planning with Graphite.

As for the namespace question, there are a number of ways for apps to handle enterprise accounts. The namespace makes it easier. You can do checks on usernames that would otherwise require maintaining a list of users somewhere youself if you use a namespace. Simple example:

if(enterpriseNamesList.includes(loadUserData().username.split('.graphite')[0].split('.')[1] {
  // This, in theory, would use an environment variable that contains a list of all enterprise clients
  // (not users but businesses) and would check to see if the user is logging in with an id in the 
  // .graphite namespace and within the root id of he organization


Hi @jehunter5811, I’m looking at this solution as well, as it makes total sense in case of a service provider (like Graphite) for enterprises and their users.

So a service provider buys a namespace, the customer (enterprise) gets a name in that namespace and the users are the enterprise employees.
A username would then be “username.enterprisename.serviceprovidername”.

Next, I want to setup a Gaia Hub for each of our customers (enterprises) to which all the enterprise users have access. Is this “now” supported in the Gaia Hub or do we need to wait for some update, @jude ?

@jehunter5811, did you already implement this?

I also want to encrypt the data on such enterprise Gaia Hub. How would that work in this scenario? Individual users retrieving such enterprise data should be able to decrypt the data, while probably encrypted with the enterprises key. Is there a HD type of encryption available so that the user keys are derived from the enterprise keys?

Gaia as user?

This is supported.


All the parts i mention?


This is in the process of being implemented with two pilot customers scheduled to launch Feb 1st. There’s still a lot to architect, so I’ll keep you posted on what works and what doesn’t.


This is supported – your enterprise customers can run their own Gaia hubs and their employees can each use it. You’d simply have each enterprise customer tell their employees to get “work” Blockstack IDs and point them to the enterprise Gaia hub. This can be facilitated by having them sign into an “onboarding” application, and having that “onboarding” application give them the recommended Gaia hub URL.


Can this enterprise gaia hub be configured to allow only access of those users having a subdomain name within the domain of that enterprise?

Or is that part of that onboarding process?


That is really great, @jehunter5811.


That would definitely be part of the onboarding process. But you could also write middleware to prevent writes from anyone that doesn’t have an enterprise subdomain name.


Yes, I was thinking in same direction, using extra protection.


@jude, could you point me to some documentation and code / CLI examples on how I could test this key derivation part? Because the whole thing hinges on that.


XOR Drive had the Gaia user choice integrated before the Jan 2019 App Mining round. I thought I would share the feedback videos from some of the TryMyUI testers here, just in case if they are useful for further improvements in this feature:



Thanks for sharing this!

Since you aren’t providing a ‘recommended gaia hub’ (i.e. your own), everyone said “I’m not sure what other provider I would use, so i’ll use the official one”. Really good feedback.

In this case, we could make it clear that using a ‘different’ provider essentially means running your own Gaia hub. That is, unless other open membership hubs become available at some time.


I’m trying to use the simple code example here to update the hello-world to use Gaia. So, I did a simple one-for-one of switch between blockstack.redirectToSignIn() and blockstack.redirectToSignInWithAuthRequest(authRequest). The code is this.

document.addEventListener("DOMContentLoaded", function(event) {

  const authRequest = blockstack.makeAuthRequest(
    ['store_write', 'publish_data'],
    blockstack.nextHour().getTime(), {
      solicitGaiaHubUrl: true
    } // new options param

  document.getElementById('signin-button').addEventListener('click', function(event) {
  document.getElementById('signout-button').addEventListener('click', function(event) {

  function showProfile(profile) {
    var person = new blockstack.Person(profile)
    document.getElementById('heading-name').innerHTML = ? : "Nameless Person"
    if(person.avatarUrl()) {
      document.getElementById('avatar-image').setAttribute('src', person.avatarUrl())
    document.getElementById('section-1').style.display = 'none'
    document.getElementById('section-2').style.display = 'block'

  if (blockstack.isUserSignedIn()) {
    var profile = blockstack.loadUserData().profile
  } else if (blockstack.isSignInPending()) {
    blockstack.handlePendingSignIn().then(function(userData) {
      window.location = window.location.origin

This code works fine if the user chooses Create new ID but fails if the user has an active profile and chooses to use it.


Or the user wants to Sign in with an existing ID


How do I go about handling these cases, for some reason, I thought the Browser would handle it but clearly I have to allow for the case in my code and take either blockstack.redirectToSignIn() or blockstack.redirectToSignInWithAuthRequest(authRequest) depending on the user.

Can someone help me out here — how after passing to the browser flow, do I handle this? Wasn’t clear to me from this original post.


The new onboarding flow does NOT work for existing users. That situation is much more complicated, because we’d have to migrate their Gaia data to a new hub, and they username is registered with the old hub URL, so you’d have to make an on-chain transaction to update it.