Authentication

The following provides some best practices to consider when working with the Smartsheet API and any access tokens (API keys), or other sensitive information.

Authentication Approaches

When choosing an authentication method, it is important to consider your integration scenario. Is the integration machine-to-machine without user interaction, or do you want user consent and interaction?

• If your scenario involes user consent and interaction, it's typically best to use OAuth with Smartsheet. Note that the Smartsheet implementation of OAuth 2.0 is a 3-legged process, which requires human intervention. See OAuth Walkthrough for details.

• If your scnenario is strictly machine-to-machine, execute raw token requests over HTTPS. It's a straightforward, secure way to authenticate. See Authentication and Access Tokens for details.

Each scenario requires an HTTP authorization header containing an access token.

NOTE: In applications and for routine requests, it is best to use a shared account, such as ticket-processor@example.com, rather than your individual work account.

WARNING: If an unauthorized user gets a copy of this token, they will be able to access all Smartsheet data that you have access to, both to read and modify on your behalf. You should keep your tokens secure and do not share them with anyone.

Access Token Best Practices

Never commit access tokens (API keys) to accessible version control systems like GitHub or BitBucket. Instead, use one of the following recommended storage options.

Recommended Storage Options

• Use an app configuration tool suitable for deploying secrets to your app, or
• Use a config file outside of source control, or
• Use environment variables set outside of source control.

If you have mistakenly deployed API keys to a publicly accessible location such as GitHub, then you should immediately revoke those API keys, revise your application to use a preferred method of key deployment, and then generate new keys.

Storing in a database

If you need to store API keys in a database, consider the following protections:

• Restrict access so API keys are only readable by the owner of the object
• Restrict read privileges to the database table
• Make sure your database or the disk the database is on is set to encrypt data at rest

NOTE: When using any Smartsheet SDK, you can use the environment variable of SMARTSHEET_ACCESS_TOKEN. If the access token is null on input to the client builder, the SDK will automatically pick up the value of that environment variable.

Revoking and Regenerating Tokens

If you've committed code to a repository before implementing these security best practices, here are some steps to resecure your API keys.

For requests with raw tokens:

1. Revoke the token
2. Create a new token

For OAuth with Smartsheet: Work through the OAuth Walkthrough to regenerate client secrets, auth codes, and tokens.