Gaia Association Tokens

I’ve received some questions over time about Gaia association tokens and how they can be used.
They weren’t designed to be immediately useful to applications, rather they are used make maintaining whitelists for private Gaia hubs easier. So for example, if I want to run a private Gaia hub, that only I can write to, I can use the Gaia configuration property for whitelisting. I’d add whitelist entries for the various owner addresses corresponding to the IDs that should be allowed to write. However, since each application has its own app-specific private key, I would need to whitelist those as well. This is where association tokens become useful.

In the Gaia authentication spec, if a request suppplies an association token, signed by a given address, the Gaia hub checks to see if that associated address is in the whitelist, and if so, it allows the request even if it is coming from an address that isn’t in the whitelist. This opens the doors to automating the process of allowing applications to write to private Gaia hubs when the user authenticates with them, rather than having to manually add new entries to the whitelist.

We have some documentation of association tokens here:

There may be other use cases for these association tokens as well (e.g., when running a Gaia hub shared amongst an organization, but disallowing writes from people outside of the organization), but the above use case is the motivation for the concept.

1 Like

@aaron If I’m reading the spec right, association tokens can only be configured for a custom gaia hub, not the default hub. Is that accurate?

That’s correct. The default gaia hub does support association tokens, but they won’t be used by it for anything, because it isn’t doing any whitelisting — it’s a public hub that will let anyone connect to it.

1 Like