This guide will walk you through the process of setting up a new `trifid-api` organization and enrolling your first host, from scratch, using the `trifid` stack and a `trifid-api` server.
This guide assumes you already have a `trifid-api` server set up, but you have *not* created a user account or organization yet. If you have, the [Quick Reference Handbook](docs/tfcli/qrh.md) may be of more use to you.
If you don't have a `trifid-api` server set up, or need help configuring it, consider checking out the [`trifid-api` Getting Started Guide](docs/trifid-api/getting_started.md) or the [`trifid-api` Quick Reference Handbook](docs/trifid-api/qrh.md).
The first step to using `tfcli` is installing it. We recommend you do this via `cargo`, rust's package manager, as it is the most fool-proof way to quickly ensure that the program is installed correctly.
Run the following command:
```shell
cargo install tfcli
```
This will install the `tfcli` binary to your Cargo `bin/` directory. You'll need to ensure that this directory is on your `PATH` - doing so is outside the scope of this guide.
## Creating your account
The first step in setting up your `trifid-api` account is creating it! This, like all other tasks, can be done via the `tfcli` program. You'll need the following on hand:
- An email address (you don't need access to the mailbox though)
- Access to the `trifid-api` server logs to get the login token
At this point, you'll need to check your `trifid-api` server logs. Look for a log message that looks like `sent magic link [long-text-here that starts with 'ml-']`.
You'll need to grab the long string of characters starting with `ml-` and going to the end of the line. It'll look something like `ml-NrrnaEm7N-6XqbDUweoNuwchI7SBCZwJQVPUDSS7T1g`.
This token only remains valid for 10 minutes, so you'll need to move relatively quickly. If the token expires, don't worry - use the `login` command as described at the end of this section to get a new token.
Once you have your magic-link token, authenticate and create your session token:
This will get a special token from `trifid-api` that allows you to modify only your 2fa settings, but not any hosts, networks, or roles. `tfcli` automatically saves this token to your computer - you don't need to worry about it.
After this, you'll need to set up 2fa before you can do any other management tasks.
In addition, approximately once every year, your session token will expire. You might also want to use multiple computers. To do this, use the `login` feature instead of `signup`:
You can then use the `magic-link` command exactly as above to renew your session token or log in on a new PC.
## Setting up 2FA
`trifid-api` enforces two-factor authentication on all accounts. You will be unable to perform any management tasks until you complete 2fa setup.
You'll need:
-`tfcli` installed
- A valid account and session token as created in the previous step
- A TOTP-compatible authenticator like Authy or Google Authenticator
After you've logged in, run the following command to get your TOTP setup code:
```shell
tfcli account mfa-setup
```
This command will give you instructions on how to complete TOTP setup. Follow the directions given. Afterwards, an auth token will be issued by trifid-api
and saved to your computer that gives you full control over your `trifid-api` resources such as networks, hosts, and roles.
This token expires after about 10 minutes. When it expires, you'll need to generate a new one by entering the code on your TOTP authenticator that you set up earlier into the following command:
This will issue another token that is valid for another 10 minutes.
### Troubleshooting 'Unauthorized' messages
If you ever see error messages about being 'unauthorized', it most likely means your authentication token has expired, and you need to run `tfcli account mfa` again. If you try that and it is successful, but you still see errors, or if `tfcli account mfa`*itself* gives you an "Unauthorized error", it means your session token has expired. Refer to the end of 'Creating your Account' above to learn how to log in again.
After getting a new session token you will always need to get a new TOTP token.
If, even after renewing your session and authentication tokens, you are still getting 'Unauthorized', it is likely an issue with your server setup. Check the trifid-api server logs or the logs of your proxy and ensure that there are no additional setup issues.
If you're still having issues, shoot a message to our mailing list on the [homepage](index.md) of this documentation and we would be glad to help you out.
