Overview

Bots are non-human Users in the Sym platform that can be issued special long-lived Tokens. Bots have a few special properties:

They exist outside of any connected identity service
They do not have emails
They can be issued long-lived JWTs

With Token-wielding Bots, you can perform operations that require authentication -- e.g. symflow commands, or Terraform ops like plan and apply -- from within programmatic contexts where human login, short-lived Tokens, and MFA would be problematic.

Bots can be issued multiple Tokens, which can in turn be revoked without impacting their host Bots. The functionality for Bots and Tokens are separated into two overarching commands: symflow bots, and symflow tokens.

📘
Don't forget the help flag!
When in doubt, -h or --help will tell you everything you need to know.

Bot Commands

Command	What it does	Example
`create`	Creates a new Bot User with the given username.	`symflow bots create steve`
`list`	Lists all Bot Users and their Token counts.	`symflow bots list`
`delete`	Deletes a Bot User with the given username and revokes all their Tokens.	`symflow bots delete steve`
`delete-identity`	Deletes a Bot's identity for a specific Service. Will launch a selection wizard for all Services available to the Organization.	`symflow bots delete-identity steve`
`update-identity`	Updates a Bot's identity for a specific Service. Will launch a selection wizard for all Services available to the Organization.	`symflow bots update-identity steve`

Token Commands

Command	What it does	Example
`issue`	Issues a new Token for a Bot User via wizard. See flags below for more details.	`symflow tokens issue --label "My First Token" -u steve -e 100d`
`list`	Lists all Bot Tokens, including their ID, creator, label, and expiry.	`symflow tokens list`
`revoke`	Revokes a single Token by ID.	`symflow tokens revoke 662b2-4110-405f`

Token usage details

`issue`

At minimum, an undecorated issue command will prompt for a Bot name and expiration window; a fully decorated command will create a Token without further user input. Only Bot name and expiry are required.

📘
Get your JWT while it's hot!
When a Token is first issued is the only time it will be displayed. Make sure you copy or export it into an env var at time of issue -- otherwise, you will not be able to retrieve it and will need to make a new Token.

Options and flags

Option	What it does	Example values
`--username` `-u`	Selects the existing Bot User for whom a Token will be issued	`-u steve`
`--expiry` `-e`	Sets the expiration date for the Token, counting from now. Acceptable units are any one of: `s` – seconds `m` – minutes `d` – days `mo` – months (30 days)	`-e 100d`
`--label` `-l`	An optional label that will be displayed in the `list` command.	`-l "Deployment token"`

`list`

The list command will display all active Tokens for an organization. The Token ID displayed here is not the JWT itself, and has no value in authentication. Rather, it is used only as an argument for the revoke command.

Token ID                              User    Created By        Expires At               Label
------------------------------------  ------  ----------------  -----------------------  ---------------------
87434498-3916-1282-948b-d630b2d1bd87  rob     [email protected]  2022-11-18 09:52:44 EST  One year expiry token
542897fa-a19a-494f-7b25-88a164a4df1e  steve   [email protected]     2021-12-03 19:59:33 EST