Manage Files

Upload, replace, list, download, and delete files programmatically through the Admin API. This is designed for CI/CD pipelines that push new builds or assets to Authgate automatically.

All endpoints are scoped to the application that owns the Admin API Key — you never pass an application ID. Files can be stored encrypted or in plain form via the store_encrypted flag, exactly like dashboard uploads.

Asynchronous processing

Uploads are processed in the background. A successful upload returns immediately with processing_status: "PENDING". Storage (and encryption, if requested) then completes asynchronously.

If your pipeline must ensure the file is live before continuing, poll Get File until processing_status is COMPLETED, and fail the pipeline on FAILED.

File object

{
  "id": "b9d8...",
  "application_id": "1a2b...",
  "name": "app-build",
  "is_public": false,
  "processing_status": "PENDING",
  "storage_status": "NOT_STORED",
  "mime_type": "application/octet-stream",
  "size_bytes": null,
  "storage_path": null,
  "original_filename": "build.bin",
  "store_encrypted": true,
  "source": "ADMIN_API",
  "created_at": "2026-06-08T12:00:00Z"
}

source is ADMIN_API for files last written through this API, or DASHBOARD for files last written through the admin panel. It always reflects the most recent write.

Upload File

Create a new file.

Endpoint: POST /files

Headers:

• Authorization: Bearer <admin_api_key> (required)
• Content-Type: multipart/form-data

Form fields:

• file (required) - The file contents
• name (required) - Logical name, unique within the application
• is_public (required) - true or false
• store_encrypted (required) - true to store encrypted at rest, false for plain

Example:

curl -X POST https://your-authgate-domain.com/api/admin/files \
  -H "Authorization: Bearer your_admin_api_key" \
  -F "name=app-build" \
  -F "is_public=false" \
  -F "store_encrypted=true" \
  -F "file=@dist/build.bin"

Response:

• 201 Created - Returns the file object (processing_status: "PENDING")

Errors:

• 401 - Invalid Admin API Key
• 409 - A file with that name already exists

Upsert File by Name

Create the file if a file with this name does not exist, or replace its contents if it does. Recommended for CI/CD — push a build by its stable name without tracking a file ID.

Endpoint: PUT /files/by-name/{name}

Headers:

• Authorization: Bearer <admin_api_key> (required)
• Content-Type: multipart/form-data

Form fields:

• file (required) - The file contents
• is_public (required) - true or false
• store_encrypted (required) - true or false

Example (GitHub Actions step):

- name: Publish build to Authgate
  run: |
    curl -X PUT "https://your-authgate-domain.com/api/admin/files/by-name/app-build" \
      -H "Authorization: Bearer ${{ secrets.AUTHGATE_ADMIN_API_KEY }}" \
      -F "is_public=false" \
      -F "store_encrypted=true" \
      -F "file=@dist/build.bin"

Response:

• 200 OK - Returns the file object

Update File

Replace a file’s contents and/or metadata by ID. The file field is optional — omit it to update metadata only.

Endpoint: PUT /files/{file_id}

Form fields:

• file (optional) - New file contents
• name (required) - Logical name
• is_public (required) - true or false
• store_encrypted (required) - true or false

Response:

• 200 OK - Returns the file object

Errors:

• 404 - File not found
• 409 - Another file already uses that name

List Files

List all files for the application.

Endpoint: GET /files

Response:

• 200 OK - Array of file objects, newest first

Get File

Retrieve a single file’s metadata. Use this to poll processing_status.

Endpoint: GET /files/{file_id}

Response:

• 200 OK - The file object

Errors:

• 404 - File not found

Download File

Stream a file’s stored bytes. Encrypted files are returned as stored (still encrypted); decrypt them client-side with your files encryption key, as the SDKs do.

Endpoint: GET /files/{file_id}/download

Response:

• 200 OK - The file stream (application/octet-stream)

Errors:

• 404 - File not found or not yet stored

Delete File

Delete a file and its stored contents.

Endpoint: DELETE /files/{file_id}

Response:

• 204 No Content - File deleted

Errors:

• 404 - File not found