

APIs and API Keys¶

Warning

We are shutting down our hosted Hub infrastructure. Please see this deprecation notice for details.

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¶

Buckets¶

Buckets provide S3-like data storage on IPFS. Just as you can create Buckets with the CLI, you can create Buckets using JavaScript with js-textile.

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.

ThreadDB¶

ThreadDB is a mongo-like database that runs on IPFS. You can use js-textile to connect to the Hub's hosted thread server (Client) to push and persist encrypted data on an IPFS-backed database.

Alternatively, you can embed local, p2p databases in your app that use remote IPFS peers for pinning and remote ThreadDB peers to relay updates (Database).

Mailboxes¶

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.

API Access¶

You can access the Hub APIs through the use of API keys.

API Keys¶

The Hub has two forms of an API key, an Account Key and a User Group Key.

Account Keys¶

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.

Access Summary¶

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

Creating Keys¶

Account Key¶

Create a new Account Key by using hub key create with the account option:

See CLI options

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.

See CLI commands

API Libraries¶

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.