OAuth Updates

Refresh Tokens Update

October 15, 2018, marks the beginning of a one year migration period for the Strava OAuth flow.

Prior to this date, anytime an athlete granted access to an application, that app received an access token with no expiration date (also called “forever tokens”). Starting on October 15, 2018, the OAuth endpoints should be used to obtain short-lived access tokens and refresh tokens instead. While the forever tokens will continue to work through October 15, 2019, all applications should be migrated to the new refresh token pattern as soon as possible.

Scopes Update

In addition, refresh tokens will come with new authorization scopes that increase transparency and control for users. The new scopes follow a pattern of {entity}:{access_level}. Note that new scopes only applies to refresh tokens, and only the legacy forever tokens can use old scopes. As before, a user may opt out of any scope that is requested by the application. It is up to the application to validate the list of scopes granted by the user and provide appropriate error messages if the scopes approved by the user are insufficient for the app to function.

The complete list of authorization scopes after this change is as follows:

  • read - Allows access to public segments, public routes, public profile data, public posts, public events, club feeds, and leaderboards. This scope matches the old default scope, except it no longer includes access to activities and certain athlete endpoints mentioned below.
  • read_all - Allows access to view private routes, private segments, and private events. This scope matches the old view_private scope, except that it no longer includes access to private activities.
  • profile:read_all - NEW! Allows access to read all profile information even if the user has set their profile visibility to “Followers” or “Only You.”
  • profile:write - NEW! Allows access to update the user’s weight and Functional Threshold Power (FTP), and access to star or unstar segments on their behalf.
  • activity:read - NEW! Allows access to read the user’s activity data for activities that are visible to “Everyone” and “Followers.”
  • activity:read_all - NEW! Allows the same access as activity:read, plus access to read the athlete’s activities that are visible to “Only You.”
  • activity:write - NEW! Allows access to create manual activities and uploads, and access to edit any activities that are visible to the app (based on activity read access level).

When existing forever tokens are exchanged for short-lived tokens following the migration instructions, the scopes from the older access token will be converted to appropriate new scopes as follows:

scope on forever token scope on short-lived access token
(no scope) read and activity:read
write activity:write and profile:write
view_private read_all, activity:read_all and profile:read_all

Translating the scopes of forever tokens this way will not broaden the access an app has to any existing users. However, in the case of a forever access token without view_private access, the short-lived access token will no longer be able to access the detailed athlete model nor the getLoggedInAthleteZones endpoint. The detailed athlete and logged in athlete zones were previously available under the default (no scope) - for apps that require this access but do not have view_private tokens, the app should request that existing users re-authorize in order to grant profile:read_all access.

If an application needs any functionality that has moved to a new scope (such as reading activities), that application must request the appropriate new scope(s) for any new users going forward.

Important Dates

October 15, 2018

New OAuth endpoints for acquiring short-lived access tokens and refresh tokens are available. New scopes are available.

January 15, 2019

Email address is no longer part of the profile:read_all scope and is removed from the athlete model.

October 15, 2019

Forever tokens are rejected by the server. Old OAuth endpoints for obtaining forever tokens are removed.

Migration Instructions

During the migration period, both forever tokens and new short-lived tokens will work for API access. To avoid interruption in functionality, application logic should be updated to use refresh tokens as soon as possible.

To migrate existing applications:

  1. Review the updated authentication docs to get an overview of how to use the new refresh token and short-lived access token pattern.
  2. Add token refresh logic to the application. This logic should check the expiration time of the access token before making a request. If it is within 1 hour of expiry, use the refresh token to obtain a new access token. Note that existing access tokens do not expire, so the refresh logic should never trigger for the old type of token.
  3. Update OAuth flow for new app users following the updated authentication instructions. The most important changes here are new scope names and use of the grant_type header.
  4. Migrate existing users to short-lived tokens and refresh tokens. To do so, make a request to the POST https://www.strava.com/oauth/token endpoint described in refreshing expired tokens, specifying grant_type = refresh_token and refresh_token = {Forever_Access_Token_For_User}. Note: This endpoint will allow a forever token to be used as a refresh token, during the migration period only.

Again, keep in mind the following key changes to the OAuth endpoints from the old forever token model:

  • You must now specify one or more scopes when requesting authorization! There is no default scope.
  • The grant_type parameter is required for token exchange.