OAuth2¶

GET /api/oauth/apps¶

Get OAuth2 clients (apps) for authenticated user with pagination (5 clients/page).

This endpoint is only accessible by FitTrackee client (first-party application).

Example request:

without parameters

GET /api/oauth/apps HTTP/1.1
Content-Type: application/json

with ‘page’ parameter

GET /api/oauth/apps?page=2 HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 SUCCESS
Content-Type: application/json

{
  "data": {
    "clients": [
      {
        "client_description": "",
        "client_id": "o22a27s2aBPUoxJbxV3UjDOx",
        "id": 1,
        "issued_at": "Thu, 14 July 2022 06:27:53 GMT",
        "name": "GPX Importer",
        "redirect_uris": [
          " https://example.com/callback"
        ],
        "scope": "profile:read workouts:write",
        "website": "https://example.com"
      }
    ]
  },
  "pagination": {
    "has_next": false,
    "has_prev": false,
    "page": 1,
    "pages": 1,
    "total": 1
  },
  "status": "success"
}

Query Parameters:

page (integer) – page for pagination (default: 1)

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again

POST /api/oauth/apps¶

Create an OAuth2 client (app) for the authenticated user.

This endpoint is only accessible by FitTrackee client (first-party application).

Example request:

POST /api/oauth/apps HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 SUCCESS
Content-Type: application/json

{
  "data": {
    "client": {
      "client_description": "",
      "client_id": "o22a27s2aBPUoxJbxV3UjDOx",
      "client_secret": "<CLIENT SECRET>",
      "id": 1,
      "issued_at": "Thu, 14 July 2022 06:27:53 GMT",
      "name": "GPX Importer",
      "redirect_uris": [
        "https://example.com/callback"
      ],
      "scope": "profile:read workouts:write",
      "website": "https://example.com"
    }
  },
  "status": "created"
}

JSON Parameters:

client_name (string) – client name
client_uri (string) – client URL
redirect_uri (array) – list of client redirect URLs (string)
scope (string) – client scopes
client_description (string) – client description (OPTIONAL)

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
400 Bad Request –
- invalid payload
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again

GET /api/oauth/apps/(string: client_client_id)¶

Get an OAuth2 client (app) by ‘client_id’.

This endpoint is only accessible by FitTrackee client (first-party application).

Example request:

GET /api/oauth/apps/o22a27s2aBPUoxJbxV3UjDOx HTTP/1.1
Content-Type: application/json

Example responses:

success

HTTP/1.1 200 SUCCESS
Content-Type: application/json

{
  "data": {
    "client": {
      "client_description": "",
      "client_id": "o22a27s2aBPUoxJbxV3UjDOx",
      "id": 1,
      "issued_at": "Thu, 14 July 2022 06:27:53 GMT",
      "name": "GPX Importer",
      "redirect_uris": [
        "https://example.com/callback"
      ],
      "scope": "profile:read workouts:write",
      "website": "https://example.com"
    }
  },
  "status": "success"
}

not found

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
  "status": "not found",
  "message": "OAuth2 client not found"
}

Parameters:

client_client_id (string) – OAuth2 client client_id

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
404 Not Found – OAuth2 client not found

GET /api/oauth/apps/(int: client_id)/by_id¶

Get an OAuth2 client (app) by id (integer value).

This endpoint is only accessible by FitTrackee client (first-party application).

Example request:

GET /api/oauth/apps/1/by_id HTTP/1.1
Content-Type: application/json

Example responses:

success

HTTP/1.1 200 SUCCESS
Content-Type: application/json

{
  "data": {
    "client": {
      "client_description": "",
      "client_id": "o22a27s2aBPUoxJbxV3UjDOx",
      "id": 1,
      "issued_at": "Thu, 14 July 2022 06:27:53 GMT",
      "name": "GPX Importer",
      "redirect_uris": [
        "https://example.com/callback"
      ],
      "scope": "profile:read workouts:write",
      "website": "https://example.com"
    }
  },
  "status": "success"
}

not found

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
  "status": "not found",
  "message": "OAuth2 client not found"
}

Parameters:

client_id (integer) – OAuth2 client id

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
404 Not Found – OAuth2 client not found

DELETE /api/oauth/apps/(int: client_id)¶

Delete an OAuth2 client (app).

This endpoint is only accessible by FitTrackee client (first-party application).

Example request:

DELETE /api/oauth/apps/1 HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

Parameters:

client_id (integer) – OAuth2 client id

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

204 No Content – OAuth2 client deleted
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
404 Not Found – OAuth2 client not found

POST /api/oauth/apps/(int: client_id)/revoke¶

Revoke all tokens associated to an OAuth2 client (app).

This endpoint is only accessible by FitTrackee client (first-party application).

Example request:

POST /api/oauth/apps/1/revoke HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 SUCCESS
Content-Type: application/json

{
  "status": "success"
}

Parameters:

client_id (integer) – OAuth2 client id

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
404 Not Found – OAuth2 client not found

POST /api/oauth/authorize¶

Authorize an OAuth2 client (app). If successful, it redirects to the client callback URL with the code to issue a token.

This endpoint is only accessible by FitTrackee client (first-party application).

Example request:

POST /api/oauth/authorize HTTP/1.1
Content-Type: multipart/form-data

Example response:

HTTP/1.1 200 SUCCESS
Content-Type: application/json

{
  "status": "success"
}

Form Parameters:

string client_id – OAuth2 client ‘client_id’
string response_type – client response type (only ‘code’ is supported by FitTrackee)
string scopes – OAuth2 client scopes
boolean confirm – confirmation (must be ‘true’)
string state – unique value to prevent cross-site request forgery (not mandatory but recommended)
string code_challenge – string generated from a code verifier (for PKCE, not mandatory but recommended)
string code_challenge_method – method used to create challenge, for instance “S256” (mandatory if code_challenge provided)

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
400 Bad Request –
- invalid payload
- errors returned by Authlib library
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again

POST /api/oauth/token¶

Issue or refresh token for a given OAuth2 client (app).

Example request:

POST /api/oauth/token HTTP/1.1
Content-Type: multipart/form-data

Example response:

HTTP/1.1 200 SUCCESS
Content-Type: application/json

{
  "access_token": "rOEHv64THCG28WcewZHRnVLUsOdUvw8NVnHKCmL57e",
  "expires_in": 864000,
  "refresh_token": "NuV9cY8VQOnrQKHTZ5pQAq2Zw7mSH0MorNPJr14AmSwD6f6I",
  "scope": ["profile:read", "workouts:write"],
  "token_type": "Bearer",
  "expires_at": 1658660147.0667062
}

Form Parameters:

string client_id – OAuth2 client ‘client_id’
string client_secret – OAuth2 client secret
string grant_type – OAuth2 client grant type (only ‘authorization_code’ (for token issue) and ‘refresh_token’ (for token refresh) are supported by FitTrackee)
string code – code generated after authorizing the client (for token issue)
string code_verifier – code verifier (for token issue with PKCE, not mandatory)
string refresh_token – refresh token (for token refresh)

Status Codes:

200 OK – success
400 Bad Request –
- errors returned by Authlib library
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again

POST /api/oauth/revoke¶

Revoke a token for a given OAuth2 client (app).

Example request:

POST /api/oauth/revoke HTTP/1.1
Content-Type: multipart/form-data

Example response:

HTTP/1.1 200 SUCCESS
Content-Type: application/json

{}

Form Parameters:

string client_id – OAuth2 client ‘client_id’
string client_secret – OAuth2 client secret
string token – access token to revoke

Status Codes:

200 OK – success
400 Bad Request –
- errors returned by Authlib library
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again