@ohos.abilityAccessCtrl (Application Access Control) (System API)

The abilityAccessCtrl module provides APIs for application permission management, including authentication, authorization, and revocation.

NOTE

• The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
• This topic describes only the system APIs provided by the module. For details about its public APIs, see @ohos.abilityAccessCtrl (Application Access Control).

Modules to Import

import abilityAccessCtrl from '@ohos.abilityAccessCtrl'

AtManager

Provides APIs for application access control.

grantUserGrantedPermission

grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void>

Grants a user_grant permission to an application. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GRANT_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

For details about the error codes, see Access Control Error Codes.

Example

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
import { BusinessError } from '@ohos.base';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application.
let permissionFlags: number = 1;
try {
    atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => {
        console.log('grantUserGrantedPermission success');
    }).catch((err: BusinessError) => {
        console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

grantUserGrantedPermission

grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void

Grants a user_grant permission to an application. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GRANT_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

For details about the error codes, see Access Control Error Codes.

Example

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
import { BusinessError } from '@ohos.base';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application.
let permissionFlags: number = 1;
try {
    atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => {
        if (err) {
            console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`);
        } else {
            console.log('grantUserGrantedPermission success');
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

revokeUserGrantedPermission

revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void>

Revokes a user_grant permission from an application. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

For details about the error codes, see Access Control Error Codes.

Example

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
import { BusinessError } from '@ohos.base';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application.
let permissionFlags: number = 1;
try {
    atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => {
        console.log('revokeUserGrantedPermission success');
    }).catch((err: BusinessError) => {
        console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

revokeUserGrantedPermission

revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void

Revokes a user_grant permission from an application. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

For details about the error codes, see Access Control Error Codes.

Example

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
import { BusinessError } from '@ohos.base';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application.
let permissionFlags: number = 1;
try {
    atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => {
        if (err) {
            console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`);
        } else {
            console.log('revokeUserGrantedPermission success');
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

getPermissionFlags

getPermissionFlags(tokenID: number, permissionName: Permissions): Promise<number>

Obtains the permission flag of an application. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS, ohos.permission.GRANT_SENSITIVE_PERMISSIONS, or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

For details about the error codes, see Access Control Error Codes.

Example

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
import { BusinessError } from '@ohos.base';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application.
try {
    atManager.getPermissionFlags(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: number) => {
        console.log(`getPermissionFlags success, data->${JSON.stringify(data)}`);
    }).catch((err: BusinessError) => {
        console.log(`getPermissionFlags fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

getVersion⁹⁺

getVersion(): Promise<number>

Obtains the data version of the permission management. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Security.AccessToken

Return value

Example

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let promise = atManager.getVersion();
promise.then((data: number) => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});

on⁹⁺

on(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback: Callback<PermissionStateChangeInfo>): void

Subscribes to permission state changes of the specified applications and permissions.

Multiple callbacks can be registered for the specified tokenIDList and permissionList.

If tokenIDList and permissionList have common values with the tokenIDList and permissionList of a callback registered, callback must be different.

System API: This is a system API.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

For details about the error codes, see Access Control Error Codes.

Example

import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl';
import bundleManager from '@ohos.bundle.bundleManager';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let appInfo: bundleManager.ApplicationInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100);
let tokenIDList: Array<number> = [appInfo.accessTokenId];
let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC'];
try {
    atManager.on('permissionStateChange', tokenIDList, permissionList, (data: abilityAccessCtrl.PermissionStateChangeInfo) => {
        console.debug('receive permission state change, data:' + JSON.stringify(data));
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

off⁹⁺

off(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback?: Callback<PermissionStateChangeInfo>): void

Unsubscribes from permission grant state changes of the specified applications and permissions. This API uses a callback to return the result.

If no callback is passed in atManager.off, all callbacks for tokenIDList and permissionList will be unregistered.

System API: This is a system API.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

For details about the error codes, see Access Control Error Codes.

Example

import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl';
import bundleManager from '@ohos.bundle.bundleManager';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let appInfo: bundleManager.ApplicationInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100);
let tokenIDList: Array<number> = [appInfo.accessTokenId];
let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC'];
try {
    atManager.off('permissionStateChange', tokenIDList, permissionList);
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

PermissionStateChangeType⁹⁺

Enumerates the operations that trigger permission grant state changes.

System API: This is a system API.

System capability: SystemCapability.Security.AccessToken

PermissionStateChangeInfo⁹⁺

Defines detailed information about the permission grant state change.

System API: This is a system API.

System capability: SystemCapability.Security.AccessToken