Copy page

Perms

Websites Puter Apps Node.js Workers

The Permissions API enables your application to request access to user data and resources such as email addresses, files and folders, apps, subdomains, and other apps' saved data.

Each request names a resource and the details that resource needs:

await puter.perms.request('email');
await puter.perms.request('fs', { path: '~/Documents/notes.txt', access: 'write' });
await puter.perms.request('folder', { name: 'Documents', access: 'write' });
await puter.perms.request('apps', { access: 'read' });
await puter.perms.request('appData', { app: 'contacts', scopes: 'read' });

The accepted values are also constants on puter.perms.Resource, puter.perms.Access, and puter.perms.Folder:

const { Resource, Access } = puter.perms;
await puter.perms.request(Resource.FS, { path: '~/Documents', access: Access.READ });

Features

Request Email
Request Folder Access
Request Apps Access
Request Several at Once
Check Without Prompting
Use Another App's Data

Request access to the user's email address 

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <button id="request-email">Request Email Access</button>
    <script>
        document.getElementById('request-email').addEventListener('click', async () => {
            const email = await puter.perms.request('email');
            if (email) {
                puter.print(`Email: ${email}`);
            } else {
                puter.print('Email access denied or not available');
            }
        });
    </script>
</body>
</html>

Request write access to the user's Documents folder 

<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>

Request read access to the user's apps 

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <button id="request-apps">Request Apps Read Access</button>
    <script>
        document.getElementById('request-apps').addEventListener('click', async () => {
            const granted = await puter.perms.request('apps');
            if (granted) {
                puter.print('Apps read access granted');
                // Now you can list the user's apps
                const apps = await puter.apps.list();
                puter.print(`User has ${apps.length} apps`);
            } else {
                puter.print('Apps read access denied');
            }
        });
    </script>
</body>
</html>

Request several things under one prompt

Pass an array to ask for everything your app needs in one call. Anything already granted is left alone, so the prompt lists only what is missing — and doesn't appear at all when it's all in place.

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <button id="setup">Set Up</button>
    <script>
        document.getElementById('setup').addEventListener('click', async () => {
            const [documents, apps, email] = await puter.perms.request([
                { resource: 'folder', name: 'Documents', access: 'write' },
                { resource: 'apps' },
                { resource: 'email' },
            ]);
            puter.print(`Documents: ${documents ?? 'denied'}`);
            puter.print(`Apps: ${apps ? 'granted' : 'denied'}`);
            puter.print(`Email: ${email ?? 'denied'}`);
        });
    </script>
</body>
</html>

Check access without prompting 

<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>

Use another app's saved data 

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <button id="request-app-data">Use another app's data</button>
    <script>
        document.getElementById('request-app-data').addEventListener('click', async () => {
            const other = await puter.apps.get('contacts');
            const granted = await puter.perms.request('appData', { app: other.uid, scopes: 'read' });
            if (granted) {
                const keys = await puter.kv.list({ appUuid: other.uid });
                puter.print(`${other.title} has ${keys.length} key(s)`);
            } else {
                puter.print('Permission denied');
            }
        });
    </script>
</body>
</html>

Functions

Guides

NEXT

request()

PREVIOUS

wasLaunchedWithItems()