How can I access files in KurocoFiles (restricted) via the API?

Files placed in KurocoFiles (restricted) (under /files/ltd/) can only be retrieved while logged in as a member who has permission to view them.
To access them over HTTP from a frontend or server-side program, obtain a file access token from the file_access_token endpoint of the Login model and insert it right after the domain in the file URL as t=<token>.

Steps

1. Create the endpoint

From [API] -> target API -> [Add], create the following endpoint.

Purpose	Model	Operation	Settings
Retrieve a file access token	Login	file_access_token	access_token_lifespan: token lifetime in seconds (300 seconds if omitted)

This endpoint must be executed as a logged-in member. Depending on the API security settings, send the request while authenticated with cookie authentication or a dynamic access token.

2. Retrieve a file access token

Sending a GET request to the Login::file_access_token endpoint returns a file access token in the following format.

{
  "file_access_token": {
    "value": "xxxxxx",
    "expiresAt": 1700000000
  }
}

• value: The file access token string.
• expiresAt: The expiration time of the token (UNIX timestamp).

3. Access the file with the token

Insert the value obtained in step 2 right after the domain of the target file's URL (e.g. https://xxxxxx.g.kuroco-img.app/files/ltd/...) as t=<value>, then send an HTTP request. This authentication method works the same way on the API domain, the Files domain, and the management domain.

https://xxxxxx.g.kuroco-img.app/t=xxxxxx/files/ltd/documents/manual.pdf

Notes

• The file access token authenticates the file access as the member who obtained the token. The view permissions (group restrictions) configured for the target folder in the File Manager are applied to that member as is. Files in folders the member is not allowed to view cannot be accessed.
• The file access token is only for accessing files under /files/ltd/. It cannot be used to authenticate other API endpoints.
• GCS/S3 private storage (/files/g/private/, /files/a/private/) is accessed via a separate signed-URL mechanism, not the file access token. As a result, the t= token access method described in this article cannot be used there.
• The lifetime can be set in seconds with access_token_lifespan. The default is 300 seconds (5 minutes). Access with an expired token results in an authentication error.
• The token carries the permissions of the logged-in member. Sharing a URL with t=... appended with unspecified users may allow users without permission to view the file, so use it only where necessary.
• Image optimization and caching behavior differ by domain. See Usage of KurocoFiles directories and domains for details.

caution

The t=... token automatically appended to API responses, such as for content extension fields (file), is different from the file access token described in this article. Its lifetime and specifications differ; see What is the expiration date of the URL with t=... attached to the files in the ltd folder?.

Related documents

• File Manager
• Usage of KurocoFiles directories and domains
• Endpoint settings
• Endpoint parameters
• What is the expiration date of the URL with t=... attached to the files in the ltd folder?
• Is it possible to redirect to any page when accessing files in the ltd directory without view permission?