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,
-hor--helpwill 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
issueAt 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 – secondsm – minutesd – daysmo – months (30 days) | -e 100d |
--label-l | An optional label that will be displayed in the list command. | -l "Deployment token" |
list
listThe 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
Updated 2 months ago