Authentication

Documentation for refresh token flow

Strava uses OAuth2 for authentication to the V3 API. OAuth allows external applications to request authorization to a user’s data. It allows users to grant and revoke API access on a per-application basis and keeps users’ authentication details safe.

All developers need to register their application before getting started. A registered application will be assigned a Client id and Client secret. The secret is used for authentication and should never be shared.

OAuth Overview

When OAuth is initiated, the user is prompted by the application to log in on the Strava website and to give consent to the requesting application. A user can opt out of the scopes requested by the application.

After the user accepts or rejects the authorization request, Strava redirects the user to a URL specified by the application. If the user authorized the application, the URL query string will include an authorization code and the scope accepted by the user. The application must complete the authentication process by exchanging the authorization code for a refresh token and short-lived access token.

Access tokens are used by applications to obtain and modify Strava resources on behalf of the authenticated athlete. Refresh tokens are used to obtain new access tokens when older ones expire.

Note that Google Sign-in will not work for applications using a mobile webview. See Google’s blog post for further information and ways to work around that limitation.

Refresh Tokens Migration

This section can be skipped for new applications integrating with the Strava API for the first time.

Existing Strava API applications that are using access tokens with no expiry time (also called “forever tokens”) will need to be updated to use the more secure refresh token pattern. The migration period is open to allow apps to update to the new system. After the migration period, forever tokens will be automatically rejected by the server and apps using them will no longer be able to access the Strava API.

Refer to the migration guide for more detailed migration instructions.

Request access

To initiate the flow, applications must redirect the user to Strava’s authorization page, GET https://www.strava.com/oauth/authorize. The page will prompt the user to consent access of their data to the application. Scopes requested by the application are shown as checked boxes, but the user may opt out of any requested scopes. If an application relies on specific scopes to function properly, the application should make that clear before and after authentication.

client_id
required integer, in query
The application’s ID, obtained during registration.
redirect_uri
required string, in query
URL to which the user will be redirected after authentication. Must be within the callback domain specified by the application. localhost and 127.0.0.1 are white-listed.
response_type
required string, in query
Must be code.
approval_prompt
string, in query
force or auto, use force to always show the authorization prompt even if the user has already authorized the current application, default is auto.
scope
required string, in query

Requested scopes, as a comma delimited string, e.g. "activity:read_all,activity:write". Applications should request only the scopes required for the application to function normally.

  • read: read public segments, public routes, public profile data, public posts, public events, club feeds, and leaderboards
  • read_all:read private routes, private segments, and private events for the user
  • profile:read_all: read all profile information even if the user has set their profile visibility to Followers or Only You
  • profile:write: update the user's weight and Functional Threshold Power (FTP), and access to star or unstar segments on their behalf
  • activity:read: read the user's activity data for activities that are visible to Everyone and Followers, excluding privacy zone data
  • activity:read_all: the same access as activity:read, plus privacy zone data and access to read the user's activities with visibility set to Only You
  • activity:write: 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
state
string, in query
Returned in the redirect URI. Useful if the authentication is done from various points in an app.

Token exchange

Strava will respond to the authorization request by redirecting the user agent to the redirect_uri provided.

If access is denied, error=access_denied will be included in the query string.

If access is accepted, code and scope parameters will be included in the query string. The code parameter contains the authorization code required to complete the authentication process. The application must now call the POST https://www.strava.com/oauth/token with its client ID and client secret to exchange the authorization code for a refresh token and short-lived access token.

The state parameter will be always included in the response if it was initially provided by the application.

client_id
required integer, in query
The application’s ID, obtained during registration.
client_secret
required string, in query
The application’s secret, obtained during registration.
code
required string, in query
The code parameter obtained in the redirect.
grant_type
required string, in query
The grant type for the request. For initial authentication, must always be "authorization_code".

A refresh token, access token, and access token expiration date will be issued upon successful authentication. The expires_at field contains the number of seconds since the Epoch when the provided access token will expire.

Example Response
{
  "token_type": "Bearer",
  "access_token": "987654321234567898765432123456789",
  "athlete": {
    #{summary athlete representation}
  },
  "refresh_token": "1234567898765432112345678987654321",
  "expires_at": 1531378346,
  "state": "STRAVA"
}

Refresh expired access tokens

Access tokens expire six hours after they are created, so they must be refreshed in order for an application to maintain access to a user’s resources. Applications use the refresh token from initial authentication to obtain new access tokens.

To refresh an access token, applications should call the POST https://www.strava.com/oauth/token endpoint, specifying grant_type: refresh_token and including the application’s refresh token for the user as an additional parameter. If the application has an access token for the user that expires in more than one hour, the existing access token will be returned. If the application’s access tokens for the user are expired or will expire in one hour (3,600 seconds) or less, a new access token will be returned. In this case, both the newer and older access tokens can be used until they expire.

A refresh token is issued back to the application after all successful requests to the POST https://www.strava.com/oauth/token endpoint. The refresh token may or may not be the same refresh token used to make the request. Applications should persist the refresh token contained in the response, and always use the most recent refresh token for subsequent requests to obtain a new access token. Once a new refresh token is returned, the older refresh token is invalidated immediately.

client_id
required integer, in query
The application’s ID, obtained during registration.
client_secret
required string, in query
The application’s secret, obtained during registration.
grant_type
required string, in query
The grant type for the request. When refreshing an access token, must always be "refresh_token".
refresh_token
required string, in query
The refresh token obtained for this user, to be used to get the next access token for this user.
Example Response
{
  "token_type": "Bearer",
  "access_token": "987654321234567898765432123456789",
  "refresh_token": "1234567898765432112345678987654321",
  "expires_at": 1531385304
}

Access the API using an Access Token

Applications use unexpired access tokens to make resource requests to the Strava API on the user’s behalf. Access tokens are required for all resource requests, and can be included by specifying the Authorization: Bearer #{access_token} header. For instance, using HTTPie:

$ http https://www.strava.com/api/v3/athlete 'Authorization: Bearer 83ebeabdec09f6670863766f792ead24d61fe3f9'

Deauthorization

Applications can revoke access to an athlete’s data. This will invalidate all refresh tokens and access tokens that the application has for the athlete, and the application will be removed from the athlete’s apps settings page. All requests made using invalidated tokens will receive a 401 Unauthorized response.

The endpoint is POST https://www.strava.com/oauth/deauthorize.

access_token
required string, in query
Responds with the refresh tokens that were revoked.