OAuth2 Token
The /oauth2/token endpoint can do the following:
- Exchange the authorization code for the initial access token and refresh token (See OAuth2 Token). This process is required when using the Authorization Code Grant Flow.
- Obtain a new access token and refresh token when the existing access token has expired (See Refresh Token).
- Initiate the Client Credentials authorization flow (See Client Credentials).
Request
| POST | /oauth2/token |
Body Parameters
| code required |
The authorization code received in the redirect as a URI parameter. The authorization code is only valid for 10 minutes. Type: string |
| grant_type required |
Supported: |
| client_id required for client apps |
This is your Fitbit API application ID from your settings on https://dev.fitbit.com. Apps set to type "client" should use this to pass their ID instead of the Authorization header. Type: string |
| redirect_uri recommended / required |
Required if specified in the redirect to the authorization page. Must be exact match. Type: URI |
| expires_in optional |
Specifies the desired access token lifetime.
Supported: 28800 Type: integer |
| code_verifier (For use with PKCE only) required |
The code verifier is used to derive the code challenge while obtaining the access code in the authorization request. This string is the base64url-encoding of a cryptographically, random-generated octet sequence. Type: string |
Request Headers
| authorization | (For use with server apps only) required |
Must be set to Basic followed by a space, then the Base64 encoded string of your application's client id and secret concatenated with a colon. For example, the Base64 encoded string, Y2xpZW50X2lkOmNsaWVudCBzZWNyZXQ=, is decoded as "client_id:client secret". Token type:Basic |
| accept | optional | The media type of the response content the client is expecting. Supported: application/json |
| accept-language | optional | The measurement unit system to use for response values. See Localization. |
| accept-locale | optional | The locale to use for response values. See Localization. |
Examples
POST https
Authorization: Basic <basic_token>
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=<authorization_code>
&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
Authorization Code Grant Flow with PKCE
POST https
Authorization: Basic <basic_token>
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=<authorization_code>
&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
&code_verifier=<code_verifier_value>
Authorization Code Grant Flow with PKCE (App Type: Client)
POST https
Content-Type: application/x-www-form-urlencoded
client_id=<client_id>&grant_type=authorization_code&code=<authorization_code>
&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
&code_verifier=<code_verifier_value>
curl -X POST "https
-H "accept: application/json" \
-H "authorization: Basic <basic_token>" \
-d "grant_type=authorization_code&code=<authorization_code> \
&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback"
Authorization Code Grant Flow with PKCE
curl -X POST "https
-H "accept: application/json" \
-H "authorization: Basic <basic_token>" \
-d "grant_type=authorization_code&code=<authorization_code> \
&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback \
&code_verifier=<code_verifier_value>"
Authorization Code Grant Flow with PKCE (App Type: Client)
curl -X POST "https
-H "accept: application/json" \
-d "client_id=<client_id>&grant_type=authorization_code&code=<authorization_code> \
&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback \
&code_verifier=<code_verifier_value>"
Response
| Element Name | Description |
| access_token | The updated active access token. |
| expires_in | The time the access token expires in seconds. |
| refresh_token | The updated active refresh token. |
| token_type | Supported: Bearer |
| user_id | The Fitbit user ID associated with the access token and refresh token |
"access_token": "eyJhbGciOiJIUzI1...",
"expires_in": 28800,
"refresh_token": "c643a63c072f0f05478e9d18b991db80ef6061e...",
"token_type": "Bearer",
"user_id": "GGNJL9"
}
Response Headers
| content-type | The media type of the response content being sent to the client. Supported: application/json |
| fitbit-rate-limit-limit | The quota number of calls. |
| fitbit-rate-limit-remaining | The number of calls remaining before hitting the rate limit. |
| fitbit-rate-limit-reset | The number of seconds until the rate limit resets. |
Note: The rate limit headers are approximate and asynchronously updated. This means that there may be a minor delay in the decrementing of remaining requests. This could result in your application receiving an unexpected 429 response if you don't track the total number of requests you make yourself.
Response Type
| HTTP Status Code | HTTP response code. List of codes are found in the Troubleshooting Guide. |
| Status Message | Description of the status code. |
| Response Body | Contains the JSON response to the API call. When errors are returned by the API call, the errorType, fieldName and message text will provide more information to the cause of the failure. |
Response Codes
| 200 | A successful request. |
| 400 | The request had bad syntax or was inherently impossible to be satisfied. |
| 401 | The request requires user authentication. |
Note: For a complete list of response codes, please refer to the Troubleshooting Guide.
Additional Information
JSON Web Tokens
Fitbit API access tokens use the JSON Web Token (JWT) format. Fitbit reserves the right to change the contents and format of these tokens at any time. Client applications should not create dependencies upon the token format.
Access tokens and refresh tokens may be up to 1,024 bytes in size.
Web Browser Compatibility
The Fitbit API and its implementation of OAuth 2.0 are designed to work with the current and one previous version of Apple Safari, Google Chrome, Microsoft Edge, and Mozilla Firefox. When a new version of a web browser is released, Fitbit begins supporting that version and stop supporting the third most recent version.
