Skip to content

Sys.Auth

Sys.Auth creates file access tokens for files on the server’s file system. A file access token is a stored, random token through which the file can be downloaded at /__api/file/token/<token>, optionally only by one End user and only until it expires.

Availability: Server

createFileAccessToken(filePath: string, options?: Exclude<FileAccessToken, 'token' | 'filePath'>): Promise<FileAccessToken>

Stores a new file access token for the file at filePath and returns it with its generated token. Call getUrl() on the result to get the download URL.

ParameterTypeDescription
filePathstringAbsolute path of the file on the server, for example from Sys.Fs.getFilePath() or Sys.Fs.writeTemporaryFile().
optionsFileAccessTokenOptional. Settings for the token; see the fields below. token and filePath are set by Lowgile.

FileAccessToken fields

FieldTypeRequiredDescription
tokenstringNoThe token. Generated by Lowgile when the token is stored.
filePathstringNoAbsolute path of the file. Set from the filePath parameter.
downloadFileNamestringNoFile name offered to the browser when downloading.
dbFileIdnumberNoID of a file stored in the database instead of on the file system; set by Sys.Files.
isPermanentbooleanYesIf false (the default), the token is deleted shortly after the next server start.
userIdUserIdTypeNoIf set, only this End user can download the file.
expiresAtDateNoAfter this time the download is refused and the token is deleted by the hourly cleanup.
expiresOnDownloadbooleanYesIf true, the token expires 5 minutes after the first download. Defaults to false.
deleteFileWhenExpiredbooleanYesIf true, the file is deleted together with the token. Defaults to false.

FileAccessToken also has the method getUrl(forDownload = false): string, which returns the relative URL /__api/file/token/<token>. With forDownload: true, it appends ?download=true.

const filePath = await Sys.Fs.writeTemporaryFile('report', csvText)
const fat = await Sys.Auth.createFileAccessToken(filePath)
const url = fat.getUrl(true) // "/__api/file/token/<token>?download=true"

Returns: Promise<FileAccessToken> · Availability: Server

Note

The type check expects options to be a complete FileAccessToken, including isPermanent, expiresOnDownload, deleteFileWhenExpired and the getUrl method, so an object literal with only some fields is rejected unless you cast it (as any). At runtime, any subset of the fields works; missing fields get the defaults above. Lowgile does not restrict filePath: any file the server can read becomes downloadable, and with deleteFileWhenExpired it is deleted. Only pass paths your own code controls.