oh so queerious

app/controllers/api/v1/authenticated/application_controller.rb

@@ -3,11 +3,19 @@ module V1
     module Authenticated
       class ApplicationController < ActionController::API
         include Doorkeeper::Rails::Helpers
-        before_action :doorkeeper_authorize!
+        before_action :authorize_scope!
         before_action :ensure_api_access_allowed
 
         private
 
+        def required_doorkeeper_scopes
+          []
+        end
+
+        def authorize_scope!
+          doorkeeper_authorize!(*required_doorkeeper_scopes)
+        end
+
         def current_user
           @current_user ||= User.find(doorkeeper_token.resource_owner_id) if doorkeeper_token
         end

app/controllers/api/v1/authenticated/heartbeats_controller.rb

@@ -25,6 +25,12 @@ def latest
             render json: { heartbeat: nil }
           end
         end
+
+        private
+
+        def required_doorkeeper_scopes
+          [ :heartbeats ]
+        end
       end
     end
   end

app/controllers/api/v1/authenticated/hours_controller.rb

@@ -16,6 +16,12 @@ def index
             total_seconds: total_seconds
           }
         end
+
+        private
+
+        def required_doorkeeper_scopes
+          [ :read ]
+        end
       end
     end
   end

app/controllers/api/v1/authenticated/me_controller.rb

@@ -24,6 +24,12 @@ def index
             }
           }
         end
+
+        private
+
+        def required_doorkeeper_scopes
+          [ :profile ]
+        end
       end
     end
   end

app/controllers/api/v1/authenticated/projects_controller.rb

@@ -18,6 +18,10 @@ def index
 
         private
 
+        def required_doorkeeper_scopes
+          [ :read ]
+        end
+
         def project_stats_query
           @project_stats_query ||= ProjectStatsQuery.new(
             user: current_user,

app/controllers/api/v1/authenticated/streak_controller.rb

@@ -7,6 +7,12 @@ def show
             streak_days: current_user.streak_days
           }
         end
+
+        private
+
+        def required_doorkeeper_scopes
+          [ :read ]
+        end
       end
     end
   end

config/initializers/doorkeeper.rb

@@ -5,7 +5,7 @@
   application_class "OauthApplication"
 
   default_scopes "profile"
-  optional_scopes "read", "admin"
+  optional_scopes "read", "heartbeats", "admin"
   enforce_configured_scopes
 
   resource_owner_authenticator do
@@ -29,7 +29,9 @@
 
   enable_application_owner confirmation: false
 
-  access_token_expires_in 16.years
+  access_token_expires_in 6.months
+
+  use_refresh_token
 
   reuse_access_token
 

config/locales/doorkeeper.en.yml

@@ -158,5 +158,6 @@ en:
         title: "OAuth authorization required"
     scopes:
       profile: Access your basic profile info (user ID, emails, Slack ID, GitHub username)
-      read: View your Hackatime stats, projects, heartbeats, and coding activity
+      read: Access your Hackatime stats, projects, and streak
+      heartbeats: Access all your raw heartbeats (may include sensitive data)
       admin: Access the Admin API on your behalf (user management, trust actions, heartbeats, and other internal tools)

config/routes.rb

@@ -271,7 +271,6 @@ def matches?(request)
         get "projects", to: "projects#index"
         # get "projects/:name", to: "projects#show", constraints: { name: /.+/ }
         get "heartbeats/latest", to: "heartbeats#latest"
-        get "api_keys", to: "api_keys#index"
       end
     end
 

db/seeds.rb

@@ -118,7 +118,7 @@
   owner: app_owner,
   redirect_uri: "hackatime://auth/callback",
   uid: "BPr5VekIV-xuQ2ZhmxbGaahJ3XVd7gM83pql-HYGYxQ",
-  scopes: [ "profile" ],
+  scopes: [ "profile", "read", "heartbeats" ],
   confidential: false,
 )
 
@@ -132,15 +132,15 @@
       application_id: app.id,
       resource_owner_id: test_user.id,
       expires_in: nil,
-      scopes: 'profile'
+      scopes: 'profile read heartbeats'
     )
   else
     token = Doorkeeper::AccessToken.find_or_create_by(
       application_id: app.id,
       resource_owner_id: test_user.id
     ) do |t|
       t.expires_in = nil
-      t.scopes = 'profile'
+      t.scopes = 'profile read'
     end
 
     token.update_column(:token, 'dev-api-key-12345')

docs/oauth/oauth-apps.md

@@ -27,7 +27,8 @@ Scopes control what data your app can access. Request only the scopes you need.
 | Scope | Description | Granted by Default |
 |-------|-------------|-------------------|
 | `profile` | Access basic profile information (user ID, email addresses, Slack ID, GitHub username, trust factor) | Yes |
-| `read` | View basic info about the user's Hackatime account | No |
+| `read` | Access your Hackatime stats, projects, and streak | No |
+| `heartbeats` | Access all your raw heartbeats (may include sensitive data) | No |
 | `admin` | Access the [Admin API](#admin-api-access) on the authorizing admin's behalf | No |
 
 If you don't specify any scopes, only the `profile` scope is granted.
@@ -111,13 +112,14 @@ POST https://hackatime.hackclub.com/oauth/token
 {
   "access_token": "abc123...",
   "token_type": "Bearer",
-  "expires_in": 504576000,
+  "expires_in": 15778476,
+  "refresh_token": "def456...",
   "scope": "profile read",
   "created_at": 1700000000
 }
 ```
 
-Access tokens are long-lived (approximately 16 years) so you typically don't need to worry about refreshing them.
+Access tokens currently expire after 6 months. Use the `refresh_token` to get a new access token without re-prompting the user for consent (see [Refreshing Tokens](#refreshing-tokens) below).
 
 ### Step 4: Make API Requests
 
@@ -128,6 +130,25 @@ GET https://hackatime.hackclub.com/api/v1/authenticated/me
 Authorization: Bearer YOUR_ACCESS_TOKEN
 ```
 
+### Refreshing Tokens
+
+Access tokens currently expire after 6 months. Before that, exchange your `refresh_token` for a new access token:
+
+```
+POST https://hackatime.hackclub.com/oauth/token
+```
+
+**Parameters (form-encoded body):**
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `client_id` | Yes | Your app's UID |
+| `client_secret` | Yes (confidential apps) | Your app's secret |
+| `grant_type` | Yes | Set to `refresh_token` |
+| `refresh_token` | Yes | The refresh token from the previous token response |
+
+The response has the same shape as the initial token exchange, including a new `refresh_token`. Store the new refresh token and discard the old one -- refresh tokens rotate on each use.
+
 ### Admin API access
 
 With a token that includes the `admin` scope, call Admin API endpoints the same way (instead of minting an Admin API key):
@@ -223,7 +244,7 @@ Returns the user's projects with time totals.
 
 ### GET /api/v1/authenticated/heartbeats/latest
 
-Returns the user's most recent heartbeat.
+Requires the `heartbeats` scope. Returns the user's most recent heartbeat.
 
 **Response:**
 
@@ -242,18 +263,6 @@ Returns the user's most recent heartbeat.
 }
 ```
 
-### GET /api/v1/authenticated/api_keys
-
-Returns the user's Hackatime API key (creates one if none exists).
-
-**Response:**
-
-```json
-{
-  "token": "abc123..."
-}
-```
-
 ## Revoking Access
 
 ### As a User

spec/requests/api/v1/authenticated_spec.rb

@@ -156,29 +156,6 @@
     end
   end
 
-  path '/api/v1/authenticated/api_keys' do
-    get('Get API keys') do
-      tags 'OAuth2-specific'
-      description 'Returns the API keys for the authenticated user. Requires an OAuth2 access token (Bearer header). Warning: This returns sensitive information.'
-      security [ { Bearer: [] } ]
-      produces 'application/json'
-
-      response(200, 'successful') do
-        let(:Authorization) { "Bearer dev-api-key-12345" }
-        schema type: :object,
-          properties: {
-            token: { type: :string, example: '550e8400-e29b-41d4-a716-446655440000' }
-          }
-        run_test!
-      end
-
-      response(401, 'unauthorized — Returned when the OAuth access token is missing or invalid.') do
-        let(:Authorization) { 'Bearer invalid' }
-        run_test!
-      end
-    end
-  end
-
   path '/api/v1/authenticated/heartbeats/latest' do
     get('Get latest heartbeat') do
       tags 'OAuth2-specific'

swagger/v1/swagger.yaml

@@ -912,29 +912,6 @@ paths:
         '401':
           description: unauthorized — Returned when the OAuth access token is missing
             or invalid.
-  "/api/v1/authenticated/api_keys":
-    get:
-      summary: Get API keys
-      tags:
-      - OAuth2-specific
-      description: 'Returns the API keys for the authenticated user. Requires an OAuth2
-        access token (Bearer header). Warning: This returns sensitive information.'
-      security:
-      - Bearer: []
-      responses:
-        '200':
-          description: successful
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  token:
-                    type: string
-                    example: 550e8400-e29b-41d4-a716-446655440000
-        '401':
-          description: unauthorized — Returned when the OAuth access token is missing
-            or invalid.
   "/api/v1/authenticated/heartbeats/latest":
     get:
       summary: Get latest heartbeat