# 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