Bot Users and Tokens

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

Suggest Edits

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

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/flag

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

Updated 23 days ago

Did this page help you?