Authentication in SyftBox

Overview

Authentication happens whenever you run the SyftBox client in the terminal (e.g., using the syftbox client command) and is required to proceed further with any SyftBox operations. Currently, authentication and identity are tied together, with your email address serving as both the unique identifier and username over the network.

First-time Registration

When using SyftBox for the first time, users will be asked to fill in their email, which will receive a registration token. The registration token can be pasted into the terminal, which will result in an access token that will be stored in <my_syftbox_path>/config.json and will be used when logging in for subsequent sessions.

The process works as follows:

1. Run syftbox client in your terminal
2. Enter your email address when prompted
3. Check your email for the registration token
4. Copy and paste the registration token into the terminal
5. SyftBox generates and stores an access token in config.json

Subsequent Logins

After the initial registration, SyftBox will automatically use the stored access token in config.json for authentication when you run the client. This provides a seamless experience for returning users.

Password Reset

If users lose their config.json file, they can regain access to their account by going through the registration flow again. Users will receive a new email and will be asked to copy a new registration token into the terminal.

The reset process follows the same steps as the initial registration:

1. Run syftbox client in your terminal
2. Enter your email address when prompted
3. Check your email for a new registration token
4. Copy and paste the new registration token into the terminal
5. SyftBox generates and stores a new access token in config.json

Development Environment

When you launch a SyftBox caching server for development with just run-server, by default it will start without authentication. During registration in development mode, the client receives a response that indicates that auth is turned off, and during login, the client just passes a base64-encoded JSON of your email address. The server will skip any JWT validation in this mode.

Important Notes

• Your email address serves as both your authentication credential and your identity within the SyftBox network
• The access token stored in config.json is crucial for maintaining your session - keep this file secure
• Authentication is mandatory for all client operations
• In development environments, authentication checks are bypassed for easier testing