Chrome Permissions API Complete Reference
7 min readchrome.permissions API Reference
Overview
The chrome.permissions API allows extensions to request and manage optional permissions at runtime, rather than declaring them all upfront in the manifest. This enables a principle of least privilege—your extension starts with minimal access and requests more only when the user needs specific features.
Key points:
- No special permission needed to use this API
- Only works with permissions declared as
optional_permissionsoroptional_host_permissionsin the manifest - Requests must be triggered by a user gesture (e.g., button click)
- Users can revoke permissions at any time via Chrome’s extension settings
Manifest Setup
To use the Permissions API, declare your optional permissions in manifest.json:
{
"name": "My Extension",
"version": "1.0",
"permissions": [
"storage",
"alarms"
],
"optional_permissions": [
"tabs",
"bookmarks",
"activeTab"
],
"optional_host_permissions": [
"https://*.example.com/*",
"https://*.google.com/*"
]
}
permissions: Required permissions granted at install timeoptional_permissions: Permissions that can be requested at runtimeoptional_host_permissions: Host permissions that can be requested at runtime
API Methods
contains(permissions, callback)
Checks whether the extension has the specified permissions granted.
chrome.permissions.contains(
{ permissions: ['tabs'], origins: ['https://*.example.com/*'] },
(result) => {
if (result) {
console.log('Permission granted!');
}
}
);
Parameters:
permissions(object): Permissions to checkpermissions(string[]): Array of permission namesorigins(string[]): Array of host patterns
callback(function): Called with boolean result
Returns: boolean - true if all specified permissions are granted
request(permissions, callback)
Requests access to the specified optional permissions. Must be called from a user gesture handler (e.g., click event).
document.getElementById('requestBtn').addEventListener('click', () => {
chrome.permissions.request(
{ permissions: ['bookmarks'] },
(granted) => {
if (granted) {
console.log('Permission granted');
} else {
console.log('Permission denied');
}
}
);
});
Parameters:
permissions(object): Permissions to requestpermissions(string[]): Array of permission namesorigins(string[]): Array of host patterns
callback(function): Called with boolean result
Returns: boolean - true if the user granted the permission
Important: This method must be called synchronously within a user gesture handler. Chrome will display a prompt asking the user to grant or deny the permission.
remove(permissions, callback)
Removes access to the specified permissions. Cannot remove required (non-optional) permissions.
chrome.permissions.remove(
{ permissions: ['bookmarks'] },
(removed) => {
if (removed) {
console.log('Permission removed successfully');
}
}
);
Parameters:
permissions(object): Permissions to removepermissions(string[]): Array of permission namesorigins(string[]): Array of host patterns
callback(function): Called with boolean result
Returns: boolean - true if the permission was removed
getAll(callback)
Retrieves all permissions granted to the extension.
chrome.permissions.getAll((permissions) => {
console.log('Granted permissions:', permissions.permissions);
console.log('Granted origins:', permissions.origins);
});
Parameters:
callback(function): Called with permissions object
Returns: { permissions: string[], origins: string[] }
Events
onAdded
Fired when permissions are added to the extension.
chrome.permissions.onAdded.addListener((permissions) => {
console.log('Permissions added:', permissions.permissions);
// Update UI to reflect new capabilities
});
onRemoved
Fired when permissions are removed from the extension.
chrome.permissions.onRemoved.addListener((permissions) => {
console.log('Permissions removed:', permissions.permissions);
// Disable features that require the removed permissions
});
Best Practices
1. Start Minimal {#1-start-minimal}
Declare only essential permissions in your manifest. Request additional permissions only when the user attempts to use a feature that requires them.
2. Explain Before Requesting {#2-explain-before-requesting}
Always show a clear explanation of why you need the permission before calling request(). Use your extension’s UI to inform users:
document.getElementById('enableFeature').addEventListener('click', () => {
// Show explanation first
if (confirm('This feature needs access to your bookmarks. Grant access?')) {
chrome.permissions.request({ permissions: ['bookmarks'] }, granted => {
if (granted) enableFeature();
});
}
});
3. Handle Denial Gracefully {#3-handle-denial-gracefully}
Users may deny permission requests. Design your UI to provide alternative functionality or clear messaging when permissions are denied.
chrome.permissions.request({ permissions: ['tabs'] }, granted => {
if (granted) {
// Full functionality
} else {
// Limited functionality - show message
showMessage('Feature unavailable without tab access');
}
});
4. Remove Unused Permissions {#4-remove-unused-permissions}
If a feature is disabled or no longer needed, consider removing the permission to reduce your extension’s attack surface:
function cleanupPermissions() {
chrome.permissions.remove({ permissions: ['bookmarks'] });
}
Code Examples
Request Optional Permission on Button Click
document.getElementById('enableBookmarks').addEventListener('click', () => {
chrome.permissions.request(
{ permissions: ['bookmarks'] },
(granted) => {
if (granted) {
document.getElementById('enableBookmarks').textContent = 'Enabled!';
}
}
);
});
Progressive Host Permission Request
document.getElementById('connectBtn').addEventListener('click', () => {
chrome.permissions.request(
{ origins: ['https://api.example.com/*'] },
(granted) => {
if (granted) {
initializeApiConnection();
}
}
);
});
Permission-Gated UI
function updateUI() {
chrome.permissions.contains({ permissions: ['bookmarks'] }, (hasPermission) => {
document.getElementById('bookmarkFeatures').style.display = hasPermission ? 'block' : 'none';
});
}
// Check on load and when permissions change
updateUI();
chrome.permissions.onAdded.addListener(updateUI);
chrome.permissions.onRemoved.addListener(updateUI);
Cross-References
- Permissions Model - Understanding Chrome’s permission system
- Advanced Permissions Tutorial - Deep dive into permission strategies
- Permissions Deep Dive - Comprehensive permission guide
Frequently Asked Questions
How do I check if I have a permission?
Use chrome.permissions.contains() to check if your extension has a specific permission granted.
Can I request permissions after installation?
Yes, use chrome.permissions.request() to request optional permissions at runtime after installation.
Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.