Authentication

Strava uses OAuth2 as an authentication protocol. It allows external applications to request authorization to a user’s private data without requiring their Strava username and password. 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 should never be shared.

Web Application Flow

The process begins by redirecting a browser to a Strava URL with a set of query parameters that indicate the type of Strava API access the application requires. Strava handles the user authentication and consent.

If the user authorizes the application, Strava will return an authorization code to the web server application. The application must still complete the process by exchanging the code for an access token.

This is done by presenting a client_id and client_secret (obtained during application registration), along with the authorization code, to Strava. Upon success, an access token will be returned that can be used to access the API on behalf of the user.

Users can revoke access on their settings page.

If you are using a mobile webview, be aware that Google Sign-in will not work.
See Google’s blog post for further information and ways to work around that limitation.

 

Request access

To request access on behalf of a user, redirect the user to Strava’s authorization page, https://www.strava.com/oauth/authorize (example). The page will prompt the user to authorize the app while providing basic information about what is being asked.

By default, applications can only view a user’s public data. The scope parameter can be used to request more access. It is recommended to only requested the minimum amount of access necessary.

Parameters

client_id: integer required
application’s ID, obtained during registration
redirect_uri: string required
URL to which the user will be redirected with the authorization code, must be to the callback domain associated with the application, or its sub-domain, localhost and 127.0.0.1 are white-listed
response_type: string required
must be ‘code’
approval_prompt: string optional
‘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: string optional
comma delimited string of ‘view_private’ and/or ‘write’, leave blank for read-only permissions.
state: string optional
returned to your application, useful if the authentication is done from various points in an app

Access scopes

public default, private activities are not returned, privacy zones are respected in stream requests
write modify activities, upload on the user’s behalf
view_private view private activities and data within privacy zones
view_private,write both ‘view_private’ and ‘write’ access

Definition

GET https://www.strava.com/oauth/authorize

Example URL (view)

https://www.strava.com/oauth/authorize?
  client_id=9
  &response_type=code
  &redirect_uri=http://testapp.com/token_exchange
  &scope=write
  &state=mystate
  &approval_prompt=force

 

Token exchange

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

On success, a code will be included in the query string. If access is denied, error=access_denied will be included in the query string. In both cases, if provided, the state argument will also be included.

Example successfully authorized HTTP response

HTTP/1.1 302 
Location: http://app.com/exchange?state=mystate&code=75e251e3ff8fff

Completing the token exchange

If the user accepts the request to share access to their Strava data, Strava will redirect back to redirect_uri with the authorization code. The application must now exchange the temporary authorization code for an access token, using its client ID and client secret.

Parameters

client_id: integer required
application’s ID, obtained during registration
client_secret: string required
application’s secret, obtained during registration
code: string required
authorization code

Returns an access_token and a summary representation of the current athlete.

Definition

POST https://www.strava.com/oauth/token

Example request

$ curl -X POST https://www.strava.com/oauth/token \
    -F client_id=5 \
    -F client_secret=7b2946535949ae70f015d696d8ac602830ece412 \
    -F code=75e251e3ff8fff

Example response

{
  "access_token": "83ebeabdec09f6670863766f792ead24d61fe3f9",
  "athlete": {
    "id": 227615,
    "resource_state": 2,
    "firstname": "John",
    "lastname": "Applestrava",
    "profile_medium": "http://pics.com/227615/medium.jpg",
    "profile": "http://pics.com/227615/large.jpg",
    "city": "San Francisco",
    "state": "California",
    "country": "United States",
    "sex": "M",
    "premium": true,
    "email": "john@applestrava.com",
    "created_at": "2008-01-01T17:44:00Z",
    "updated_at": "2013-09-04T20:00:50Z"
  }
}

Access the API using an Access Token

The application will now be able to make requests on the user’s behalf using the access_token query string parameter (GET) or POST/PUT body, or the Authorization header.

Applications should check for a 401 Unauthorized response. Access for those tokens has been revoked by the user.

Example requests

$ curl -G https://www.strava.com/api/v3/athlete \
    -H "Authorization: Bearer 83ebeabdec09f6670863766f792ead24d61fe3f9"

$ curl -G https://www.strava.com/api/v3/athlete \
    -d access_token=83ebeabdec09f6670863766f792ead24d61fe3f9

 

Deauthorization

Allows an application to revoke its access to an athlete’s data. This will invalidate all access tokens associated with the ‘athlete,application’ pair used to create the token. The application will be removed from the Athlete Settings page on Strava. All requests made using invalidated tokens will receive a 401 Unauthorized response.

Parameters

access_token: string required

Responds with the access token submitted with the request.

Definition

POST https://www.strava.com/oauth/deauthorize

Example request

$ curl -X POST https://www.strava.com/oauth/deauthorize \
    -H "Authorization: Bearer 83ebeabdec09f6670863766f792ead24d61fe3f9"

Example response

{
  "access_token": "83ebeabdec09f6670863766f792ead24d61fe3f9"
}