Beautiful Open-Source Form Builder
Fix export status API docs and secure token polling (#1314)
Michael Lipab2971a2e59a
diff --git a/api/app/Http/Controllers/Forms/FormSubmissionController.php b/api/app/Http/Controllers/Forms/FormSubmissionController.phpindex ffb8e079a..3b44a21aa 100644--- a/api/app/Http/Controllers/Forms/FormSubmissionController.php+++ b/api/app/Http/Controllers/Forms/FormSubmissionController.php@@ -123,10 +123,14 @@ class FormSubmissionController extends Controller{$this->authorize('view', $form);+ if ($token = Auth::user()->currentAccessToken()) {+ abort_unless($token->can('forms-read'), 403);+ }+$cacheKey = $exportService->getCacheKey($jobId);$jobData = Cache::get($cacheKey);- if (!$jobData) {+ if (!$jobData || ($jobData['form_id'] ?? null) !== $form->id) {return $this->error(['message' => 'Export job not found or has expired.'], 404);diff --git a/api/config/sanctum-routes.php b/api/config/sanctum-routes.phpindex c9cfde952..f76fb724c 100644--- a/api/config/sanctum-routes.php+++ b/api/config/sanctum-routes.php@@ -13,6 +13,7 @@ return ['open.forms.submissions.index','open.forms.submissions.update','open.forms.submissions.export',+ 'open.forms.submissions.export.status','open.forms.submissions.destroy',// Form Integrationsdiff --git a/api/tests/Feature/Forms/FormSubmissionExportTest.php b/api/tests/Feature/Forms/FormSubmissionExportTest.phpindex 29453910a..ed0011d6c 100644--- a/api/tests/Feature/Forms/FormSubmissionExportTest.php+++ b/api/tests/Feature/Forms/FormSubmissionExportTest.php@@ -542,3 +542,81 @@ it('allows export status polling when the general api rate limit is exhausted',->assertSuccessful()->assertJsonPath('status', 'processing');});++it('serves export status at the documented path with the documented fields', function (string $authentication) {+ $user = $this->createProUser();+ if ($authentication === 'token') {+ $this->withToken($user->createToken('Export status', ['forms-read'])->plainTextToken);+ } else {+ $this->actingAsProUser($user);+ }+ $workspace = $this->createUserWorkspace($user);+ $form = $this->createForm($user, $workspace);++ $jobId = app(FormExportService::class)->initializeAsyncExport($form, $user->id);++ // Keep in sync with docs/api-reference/submissions/export-status.mdx+ $response = $this->getJson("/open/forms/{$form->id}/submissions/export/status/{$jobId}")+ ->assertSuccessful()+ ->assertJsonPath('job_id', $jobId)+ ->assertJsonPath('status', 'queued')+ ->assertJsonPath('progress', 0);++ expect(array_keys($response->json()))->toEqualCanonicalizing([+ 'job_id',+ 'status',+ 'progress',+ 'processed_submissions',+ 'total_submissions',+ 'file_url',+ 'error_message',+ 'expires_at',+ 'created_at',+ 'updated_at',+ ]);+})->with(['session', 'token']);++it('rejects export status tokens without read access', function (array $abilities) {+ $user = $this->createProUser();+ $workspace = $this->createUserWorkspace($user);+ $form = $this->createForm($user, $workspace);+ $jobId = app(FormExportService::class)->initializeAsyncExport($form, $user->id);++ $this->withToken($user->createToken('Export status', $abilities)->plainTextToken)+ ->getJson("/open/forms/{$form->id}/submissions/export/status/{$jobId}")+ ->assertForbidden();+})->with([+ 'write only' => [['forms-write']],+ 'integration management only' => [['manage-integrations']],+ 'no abilities' => [[]],+]);++it('rejects export jobs belonging to another form', function (string $authentication) {+ $user = $this->createProUser();+ $workspace = $this->createUserWorkspace($user);+ $form = $this->createForm($user, $workspace);+ $otherUser = $this->createProUser();+ $otherForm = $this->createForm($otherUser, $this->createUserWorkspace($otherUser));+ $jobId = app(FormExportService::class)->initializeAsyncExport($otherForm, $otherUser->id);++ if ($authentication === 'token') {+ $this->withToken($user->createToken('Export status', ['forms-read'])->plainTextToken);+ } else {+ $this->actingAsProUser($user);+ }++ $this->getJson("/open/forms/{$form->id}/submissions/export/status/{$jobId}")+ ->assertNotFound();+ $this->getJson("/open/forms/{$otherForm->id}/submissions/export/status/{$jobId}")+ ->assertForbidden();+})->with(['session', 'token']);++it('returns not found for unknown export jobs', function () {+ $user = $this->createProUser();+ $form = $this->createForm($user, $this->createUserWorkspace($user));+ $jobId = (string) Str::uuid();++ $this->withToken($user->createToken('Export status', ['forms-read'])->plainTextToken)+ ->getJson("/open/forms/{$form->id}/submissions/export/status/{$jobId}")+ ->assertNotFound();+});diff --git a/docs/api-reference/changelog.mdx b/docs/api-reference/changelog.mdxindex 341f3e217..bb94725e0 100644--- a/docs/api-reference/changelog.mdx+++ b/docs/api-reference/changelog.mdx@@ -3,6 +3,18 @@ title: "Changelog"description: "Notable updates to the OpnForm API."---+## 2026-10-07 – Export status polling with API tokens++Personal Access Tokens with `forms-read` can now poll asynchronous exports at+`GET /open/forms/{id}/submissions/export/status/{job_id}`. The previously documented+`/export/{job_id}/status` path was incorrect.++The job must belong to the requested form, and you must have access to that form.+A job from another form returns `404`.++The response documentation now includes the initial `queued` status and matches+the ten fields returned by the API, including `null` values for fields that do not apply.+## 2026-10-01 – Removed unused public form users endpoint`GET /forms/{form}/users` has been removed and now returns `404`. The application does not use this endpoint.@@ -80,4 +92,4 @@ The first public version of the OpnForm REST API is live! You can now:* Retrieve and manage submissions* Generate personal access tokens with granular abilities-Stay tuned for more endpoints and features.\ No newline at end of file+Stay tuned for more endpoints and features.diff --git a/docs/api-reference/openapi.yaml b/docs/api-reference/openapi.yamlindex d5898a7a7..f0038fc7e 100644--- a/docs/api-reference/openapi.yaml+++ b/docs/api-reference/openapi.yaml@@ -754,13 +754,13 @@ paths:example: "Export started. Large export will be processed in the background."job_id:type: string- example: "export_abc123def456"+ example: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"is_async:type: booleanexample: true"403":description: Forbidden- "/open/forms/{id}/submissions/export/{job_id}/status":+ "/open/forms/{id}/submissions/export/status/{job_id}":get:tags:- Submissions@@ -788,7 +788,7 @@ paths:schema:$ref: "#/components/schemas/ExportJobStatus""404":- description: "Export job not found or has expired"+ description: "Export job not found, has expired, or belongs to another form""403":description: Forbidden"/open/forms/{id}/submissions/{submission_id}":@@ -1571,19 +1571,13 @@ components:properties:status:type: string- enum: [processing, completed, failed]+ enum: [queued, processing, completed, failed]description: "Current status of the export job"progress:type: numberminimum: 0maximum: 100description: "Completion percentage (0-100)"- form_id:- type: number- description: "ID of the form being exported"- user_id:- type: number- description: "ID of the user who initiated the export"job_id:type: stringdescription: "Export job identifier"diff --git a/docs/api-reference/submissions/export-status.mdx b/docs/api-reference/submissions/export-status.mdxindex 2613bf836..296dde072 100644--- a/docs/api-reference/submissions/export-status.mdx+++ b/docs/api-reference/submissions/export-status.mdx@@ -1,5 +1,5 @@----openapi: get /open/forms/{id}/submissions/export/{job_id}/status+openapi: get /open/forms/{id}/submissions/export/status/{job_id}---# Check Export Status@@ -13,7 +13,7 @@ Requires `forms-read` ability.## Request```http-GET /open/forms/{id}/submissions/export/{job_id}/status HTTP/1.1+GET /open/forms/{id}/submissions/export/status/{job_id} HTTP/1.1Host: api.opnform.comAuthorization: Bearer <token>```@@ -33,13 +33,14 @@ Authorization: Bearer <token>{"status": "processing","progress": 65,- "form_id": 123,- "user_id": 456,"processed_submissions": 650,"total_submissions": 1000,+ "file_url": null,+ "error_message": null,+ "expires_at": null,"created_at": "2024-06-12T09:15:23.000Z","updated_at": "2024-06-12T09:16:10.000Z",- "job_id": "export_abc123def456"+ "job_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"}```@@ -49,15 +50,14 @@ Authorization: Bearer <token>{"status": "completed","progress": 100,- "form_id": 123,- "user_id": 456,"processed_submissions": 1000,"total_submissions": 1000,"file_url": "https://storage.example.com/exports/form-123-submissions-2024-06-12-09-15-23.csv",+ "error_message": null,"expires_at": "2024-06-13T09:15:23.000Z","created_at": "2024-06-12T09:15:23.000Z","updated_at": "2024-06-12T09:16:30.000Z",- "job_id": "export_abc123def456"+ "job_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"}```@@ -67,12 +67,14 @@ Authorization: Bearer <token>{"status": "failed","progress": 0,- "form_id": 123,- "user_id": 456,+ "processed_submissions": null,+ "total_submissions": null,+ "file_url": null,"error_message": "Database connection timeout",+ "expires_at": null,"created_at": "2024-06-12T09:15:23.000Z","updated_at": "2024-06-12T09:15:45.000Z",- "job_id": "export_abc123def456"+ "job_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"}```@@ -80,10 +82,8 @@ Authorization: Bearer <token>| Field | Type | Description || ----------------------- | ------ | ---------------------------------------------------- |-| `status` | string | Job status: `processing`, `completed`, or `failed` |+| `status` | string | Job status: `queued`, `processing`, `completed`, or `failed` || `progress` | number | Completion percentage (0-100) |-| `form_id` | number | ID of the form being exported |-| `user_id` | number | ID of the user who initiated the export || `job_id` | string | Export job identifier || `processed_submissions` | number | Number of submissions processed so far || `total_submissions` | number | Total number of submissions to process |@@ -94,8 +94,8 @@ Authorization: Bearer <token>| `updated_at` | string | Last update timestamp |<Note>- Only `status`, `progress`, `form_id`, `user_id`, `job_id`, `created_at`, and- `updated_at` are always present. Other fields appear based on the job state.+ Every field is always present. Fields that do not apply to the current job+ state are `null`.</Note><Warning>@@ -105,7 +105,7 @@ Authorization: Bearer <token>## Error Responses-`404 Not Found` – Export job not found or has expired.+`404 Not Found` – Export job not found, has expired, or belongs to another form.`403 Forbidden` – The token lacks `forms-read` or you don't have access.diff --git a/docs/api-reference/submissions/export-submissions-csv.mdx b/docs/api-reference/submissions/export-submissions-csv.mdxindex 8c8ede00a..d8a6533f2 100644--- a/docs/api-reference/submissions/export-submissions-csv.mdx+++ b/docs/api-reference/submissions/export-submissions-csv.mdx@@ -59,7 +59,7 @@ The API automatically determines whether to process the export synchronously or```json{"message": "Export started. Large export will be processed in the background.",- "job_id": "export_abc123def456",+ "job_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d","is_async": true}```