Starting 2/14/22: Conversion of Legacy API Tokens to have Granular Scopes


On 2/14/22, Samsara will begin converting in-use Legacy API Tokens to have Granular Scopes

To improve security for customers sharing data via API, we are going to slowly convert Legacy API Tokens (all tokens created prior to February 2022) to have Granular Scopes.


Open Questions or Concerns?

Feel free to reach out to support or your Samsara point of contact and they will assist you with any issues you may face or questions you may have

What are Granular Scopes?

Granular Scopes are a way for you to limit which types of data an API token can access. The benefit of this is when you share your API token externally for integration purposes, you can give that token permissions to access only the necessary data needed for that integration. Samsara highly recommend you limit your scopes to only the absolutely necessary data. Read more about Granular Scopes in the Authentication developer guide.

How will Samsara decide which Granular Scopes to apply?

Samsara will look at all the API endpoints called in the last 1 year by a Legacy API Token and automatically add the Granular Scopes that are required in order to call those API endpoints. We will do this to ensure that live integrations don't break but had added security through automatically limiting the scopes needed.

If your Legacy API Token has not been used to make API calls at all in the last year, we will apply the default scopes mentioned in the Authentication developer guide.

What if I want to apply different scopes than what Samsara applies?

Before Samsara automatically converts, you can convert existing Legacy API Tokens to have granular scopes and then edit the scopes directly yourself. Once you do this, this token will not be impacted by the conversion.

If you want to edit the automatically applied scopes after a Legacy API Token has been converted by Samsara, it is as easy as going to the API Tokens page and editing the scopes directly for that specific token.

I'm getting an error when making a call to an endpoint after the conversion

If you notice your API token has been converted to have Granular Scopes, and you can't call an endpoint due to permissions issues, make sure you have selected the Scope that allows access to call that endpoint in the API tokens page.

Does this change apply to Oauth 2.0 apps and the permissions they have?

This conversion will not impact OAuth 2.0 apps and tokens. This conversion only applies to API tokens.