APIs and API Keys¶
Textile has three API categories for building an application: Threads, Buckets, and Mailboxes.
To use any of these APIs, you need to use API keys. Read Google's API key best practices for an overview of how API keys will be used here.
This section will cover the overview of the three APIs and how to work with the API keys.
A Tour of Available APIs¶
The js-textile library allows you to create and edit Buckets owned by you or your organization using an account key. Alternatively, you can use Buckets to store your user's data using a user group key.
Alternatively, you can embed local, p2p databases in your app that use remote IPFS peers for pinning and remote ThreadDB peers to relay updates (
The Users API provides tools for sending and receiving messages between Hub users. Mailboxes are built on ThreadDB.
Hub mailboxes are a unique inboxing and messaging system designed for modern apps where users hold private keys linked to their identity. With just their private and public key, a user can send and receive encrypted messages to other users in your app.
You can access the Hub APIs through the use of API keys.
The Hub has two forms of an API key, an Account Key and a User Group Key.
Account keys grant access to the developer's resources (e.g. Buckets you create using the command-line interface).
If Account Keys are generated with the
-o (organization) flag, they will grant access to that organization's resources.
Example uses include, integrating your Buckets into CI, dashboards, team messaging integration, etc.
User Group Keys¶
User group keys only grant access to new resources for new identities, not those of the developer.
User group keys can be used in an application to allow app users to leverage Hub APIs (e.g. create and push new buckets). User group keys do not have permission to access the developer or organization resources, but threads and buckets created using these keys are counted against API limits.
Key Use and Security¶
API keys are project-centric credentials that you can use to provision your Hub resources to end-users (either within your organization or in a public app). We recommend reading this thorough overview of API key design and best practices.
Below is a summary of the Hub resources you may create and access with each key type.
|Resource example||Owner||CLI||Required Key|
|Developer Threads||Hub Developer||create, access||Account Key|
|Developer Buckets||Hub Developer||create, access||Account Key|
|Organization Threads||Hub Developer(s)||create, access||Account Key|
|Organization Buckets||Hub Developer(s)||create, access||Account Key|
|User Threads||App User||User Group Key|
|User Buckets||App User||User Group Key|
Create a new Account Key by using
hub key create with the
User Group Key¶
Create a new User Group Key by using
hub key create with the
user group option.
If you're building an app in an organization, use:
HUB_ORG=<org name> hub key create
To link a new key to the organization, not your personal account.
Currently, there are no migration tools, so we recommend creating a new organization or using an existing organization when starting a new app (see Organizations).
➜ hub key create # select the 'user' option ✔ user KEY SECRET TYPE bqab5csdh...no6jjezox4 bm2tk476yivwlw...3a4cayll7ztha user > Success! Created new API key and secret
Non-signing User Group keys¶
You can use insecure keys with the API by creating non-signing keys. These keys are meant to be used during development only. Read the tutorial on development mode to use these keys.
Updating User Group keys¶
You can replace your keys in your app at any time and the user will still have access to their Threads and Buckets as long as the key is connected to the same developer or organization.
You can find all the remote Thread and Bucket APIs in the
textile libraries below. These libraries are meant to work in combination with the
threads libraries when you want to create and manage Thread databases in your app.