Admin Tokens

Last modified on October 18, 2023

Admin tokens provide tokenized account access for automated StrongDM use. They can be utilized for administrative tasks, such as the following:

  • Auditing
  • Managing users
  • Managing roles
  • Managing resources
  • Managing gateways and relays
  • Managing access
  • Managing Secret Stores

This article describes how to create, manage, and use admin tokens.

Create Admin Tokens

Admin tokens are generated in the Admin UI under Access > API & Admin Tokens. To create an admin token, follow these steps:

  1. Make sure you have admin access to the Admin UI.
  2. On Access > API & Admin Tokens, click Add token.
  3. On the Create Admin Token page, give your token a name.
  4. Specify when the token expires.
Create Admin Token
Create Admin Token
  1. Choose which rights this admin token grants and select the appropriate options for your admin token use case.
Create Admin Token
Create Admin Token
  1. Click Create. The token appears in a modal.
  2. Copy the token and keep it somewhere safe. The token only displays once.
Admin Token Secret
Admin Token Secret

Authentication

There are two methods to authenticate the CLI with an admin token: with an environment variable or through the sdm login command.

Environment variable

The CLI references the environment variable SDM_ADMIN_TOKEN if it is set. You can set this in your shell by using export:

export SDM_ADMIN_TOKEN='<TOKEN_VALUE>'

Login command

The CLI can use the token directly if the --admin-token flag is used:

sdm login --admin-token='<TOKEN_VALUE>'

General Usage

Once authenticated with an admin token, you can run any sdm admin command granted to the token. No other commands (for example, sdm status) work using an admin token, regardless of permission level.

You can run any of the following commands that you have granted to the token once you are authenticated with the token:

  • User commands: sdm admin users list
  • Role commands: sdm admin roles list
  • Datasource commands: sdm admin datasources list
  • Server commands: sdm admin servers list
  • Relay commands: sdm admin relays list. Note that the relays list command requires the token to have been granted datasources list; without it, relays list does not work because it provides some information on the connected datasources for each relay.

Rotate Admin Tokens

Rotating an admin token generates a new secret while maintaining the name and permissions. We recommend doing so if you believe a token has been compromised, a user with access to the token has left your organization, or a user who owns the admin token is suspended.

To rotate a token, use these steps.

  1. Find the token on the API & Admin Tokens page.
  2. Click to Rotate. A tooltip alerts you that the existing secret will be unable to authenticate, and existing authentications will expire after 24 hours.
Rotate Admin Token
Rotate Admin Token
  1. Click Rotate to regenerate the token secret and expire the existing token after 24 hours.

Delete Admin Tokens

Once a token is rotated or deleted, the token immediately loses its ability to authenticate commands.

Admin Tokens Created by Suspended Users

What happens to admin tokens that are owned by a suspended user? Admin tokens are still usable even if the user who created them is suspended.

When suspending a user, the Admin UI lists the admin tokens created by that user and asks if they should be deleted. Select No to keep them.

After confirming suspension, you can see in section Access > API & Admin Tokens that the admin tokens continue to be owned by the suspended user and remain usable. For the admin tokens that are still needed, rotate the credentials to deactivate the existing token secret and generate a new one.