About API Tokens

API tokens are an alternative way to authentication to scalr.io when using the Scalr API or CLI. There are two type of tokens, personal and service account tokens. Personal tokens should be used for your own use and service account tokens should be used for any integrations or jobs the are executing on behalf of your organization.

Creating Tokens

Personal Token

Personal access tokens are created through your user profile:

Click on personal access tokens and then generate a token. Ensure that you save it once it is generated as you cannot recover it once the window is closed:

Service Account Tokens

Service account tokens are created and managed within the IAM section of the account scope in Scalr:

When creating a service account, you must give it an access policy that defines the permissions it will have as well as the scope the permissions are applied to.

A service account can have multiple tokens assigned to it and they are all managed within the accounts profile:

Keeping Tokens Secure

Access tokens should be treated like passwords. If a token is being used as part of a Scalr workspace, ensure that the sensitive option is always enabled in the variable settings to make it encrypted and hidden in the UI. We also recommend rotating your tokens on a consistent basis to avoid tokens from being compromised.

Deleting Tokens

Any unused tokens should always be deleted to ensure they are not leaked or compromised.

Personal Tokens

Personal tokens can be deleted by going to your profile and then clicking on the trash can on the line of the token:

Service Account Tokens

Service account tokens can be deleted by going to the service account and then clicking on the red "X" can on the line of the token:

GitHub Secret Scanning

Scalr supports the ability to do Github Secret Scanning to ensure Scalr API tokens do not end up visible in code stored in Github. To enable this, go to your GitHub settings, specifically Code Security and then Global Settings. In there, click Scan for non-provider patterns and under Custom patterns, select New Pattern:

Once you are on the new pattern page, enter the following:

Secret Format: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\.eyJpc3MiOiJzY2Fscj[a-zA-Z0-9_-]_\.[a-zA-Z0-9_-]_

Before Secret: \A|[^0-9A-Za-z]

After Secret: \z|[^0-9A-Za-z]

Upon saving the information above the secret scanning will be enabled and you will be notified if any Scalr API tokens make it into your code stored in GitHub.

The token must have been created on or after April, 11th 2024 for the secret scanning to work correctly.

Note: Scalr is currently awaiting approval from GitHub to join the [GitHub Secret Scanning program](https://docs.github.com/en/code-security/secret-scanning/secret-scanning-partner-program).

API Token Reports

The API token report in the reporting section of Scalr will help administrators identify Scalr API tokens that have not been rotated in awhile or ever used to reduce the risk of unauthrozied access. See more in the reporting section of the docs.