Request Access to User Resources with the Permissions API

Your app can now ask users for access to their folders, files, apps, subdomains, email address, and more in their Puter account, with the Permissions API in Puter.js.

By default, a Puter.js app runs in a sandbox and can only reach its own files and data. With puter.perms, your app can ask for more, and the user decides whether to allow it.

Requesting Access

Pass puter.perms.request() the resource you want and its details. Here we ask for write access to the Documents folder in the user's Puter account, then write a file to it:

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <button id="request-documents">Request Documents Write Access</button>
    <script>
        document.getElementById('request-documents').addEventListener('click', async () => {
            const documentsPath = await puter.perms.request('folder', { name: 'Documents', access: 'write' });
            if (documentsPath) {
                puter.print(`Documents path: ${documentsPath}`);
                // Now you can write to the Documents folder
                await puter.fs.write(`${documentsPath}/my-file.txt`, 'Hello from Documents!');
                puter.print('File written to Documents folder');
            } else {
                puter.print('Documents write access denied');
            }
        });
    </script>
</body>
</html>

The user gets a prompt to allow or deny. If they allow it, the call resolves to the folder's path, and if they deny it, it resolves to undefined. Once access is granted, the user isn't asked again.

Checking Access

puter.perms.check() tells you whether access is already granted, without showing a prompt. You can use it to decide what to show before asking, such as whether to display a "Connect Documents" button.

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        (async () => {
            // Never shows a dialog, it only reports what is already granted.
            const granted = await puter.perms.check('folder', { name: 'Documents', access: 'write' });
            puter.print(granted
                ? 'Documents write access is already granted'
                : 'Documents write access has not been granted yet');
        })();
    </script>
</body>
</html>

Each resource takes its own details, and you can request several resources under a single prompt. The Permissions documentation lists every resource and its options.

Get Started Now

With puter.perms.request() and puter.perms.check(), your app can work with the folders, files, apps, subdomains, and more in the user's Puter account once they allow it, instead of staying limited to its own data.

Just add one library to your project:

// npm install @heyputer/puter.js
import { puter } from '@heyputer/puter.js';

Or add one script tag to your HTML:

<script src="https://js.puter.com/v2/"></script>

No API keys or backend needed. Start requesting access to users' Puter resources in your app today.

Related

• Permissions API Documentation
• Recipe: Ask for Access
• Getting Started with Puter.js