Auth
🔐 Auth API methods allow developers to request interactive access to a user's 3Box profile and spaces. Authentication is required to perform stateful operations on 3Box such as updating data, decrypting private data, and generally interacting with the user's data stores in a meaningful way.
Onboarding (SSO): The Auth API, combined with the Profiles API and Storage API, enable frictionless user onboarding and SSO using 3Box. Developers can authenticate a user and then read existing data from their profile and spaces to streamline the onboarding process.
Static
Stateful
box.auth
Authenticates the 3Box associated with the given address.
Kind: static method of Box
Returns: Box - the 3Box instance for the given address
Param | Type | Description |
address |
| An ethereum address |
ethereumProvider |
| An ethereum provider |
opts |
| Optional parameters |
opts.consentCallback |
| A function that will be called when the user has consented to opening the box |
opts.pinningNode |
| A string with an ipfs multi-address to a 3box pinning node |
opts.ipfs |
| A js-ipfs ipfs object |
opts.addressServer |
| URL of the Address Server |
const box = await Box.openBox(0x234..., window.ethereum)
Box.openBoxonly needs to be called once in a user flow.
Check if the address is currently authenticated.
Kind: static method of Box
Returns: Boolean - Returns true if the user is logged in.
Param | Type | Description |
address |
| An ethereum address |
Creates an 3Box instance. This 3Box instance is not associated with a given address (use box.auth for this).
Kind: static method of Box
Returns: Box - the 3Box instance
Param | Type | Description |
ethereumProvider |
| An ethereum provider |
const box = await Box.create(window.ethereum)
Authenticates a space in the user's 3Box.
Kind: instance method of Box
Returns: Space - the Space instance for the given space name
Param | Type | Description |
name |
| The name of the space |
opts |
| Optional parameters |
opts.consentCallback |
| A function that will be called when the user has consented to opening the space |
opts.onSyncDone |
| A function that will be called when the space has finished syncing with the pinning node |
const space = await box.openSpace("my-dapp")
Authenticates a user's ethereum address to a 3Box instance. Authenticates a user to one or more spaces. Use after Box.create and before box.openSpace.
Kind: instance method of Box
Param | Type | Description |
space |
| An array of space names to authenticate |
address |
| An object containing the user's address |
await box.auth(['space1', 'space2', 'space3'], { address });
Kind: instance property of Box
Properties
Name | Type | Description |
syncDone |
| A promise that is resolved when the box is synced |
Kind: instance property of Space
Properties
Name | Type | Description |
syncDone |
| A promise that is resolved when the space data is synced |
Sets the callback function that will be called once the users 3Box DB is fully synced with the latest updates.
Kind: instance method of Box
Param | Type | Description |
syncDone |
| The function that will be called |
Closes the 3box instance and clears local cache. If you call this, users will need to re-authenticate by signing a consent message the next time you call openBox.
Kind: instance method of Box
