Bot Users and Tokens

Create Bot Users and issue long-lived JWTs for using symflow in programmatic contexts.

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

CommandWhat it doesExample
createCreates a new Bot User with the given username.symflow bots create steve
listLists all Bot Users and their Token counts.symflow bots list
deleteDeletes a Bot User with the given username and revokes all their Tokens.symflow bots delete steve
delete-identityDeletes 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-identityUpdates 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

CommandWhat it doesExample
issueIssues 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
listLists all Bot Tokens, including their ID, creator, label, and expiry.symflow tokens list
revokeRevokes 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

OptionWhat it doesExample 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