Skip to content

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.php
index 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.php
index 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 Integrations
diff --git a/api/tests/Feature/Forms/FormSubmissionExportTest.php b/api/tests/Feature/Forms/FormSubmissionExportTest.php
index 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.mdx
index 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.yaml
index 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: boolean
example: 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: number
minimum: 0
maximum: 100
description: "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: string
description: "Export job identifier"
diff --git a/docs/api-reference/submissions/export-status.mdx b/docs/api-reference/submissions/export-status.mdx
index 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.1
Host: api.opnform.com
Authorization: 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.mdx
index 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
}
```