@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 '@kit.AbilityKit';

AtManager

Provides APIs for application access control.

Invoking the AtManager API depends on the tokenID. The system application can obtain the tokenID by calling the bundleManager.getBundleInfoSync or bundleManager.getBundleInfoForSelfSync.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
tokenID	number	Yes	ID of the target application, which can be obtained from the accessTokenId field of ApplicationInfo in BundleInfo of the application.
permissionName	Permissions	Yes	Permission to grant. For details, see Application Permissions.
permissionFlags	number	Yes	Permission flag. - 1: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission. - 2: No dialog box will be displayed the next time if the user denies authorization for the permission. The permission must be granted by the user in Settings. - 64: The permission is given just once if the user allows the permission only this time. The authorization is canceled after the application is switched to the background or exits.

Return value

Type	Description
Promise<void>	Promise that returns no result.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission "ohos.permission.GRANT_SENSITIVE_PERMISSIONS".
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001	Invalid parameter. The tokenID is 0, the permissionName exceeds 256 characters or is not declared in the module.json file, or the flags value is invalid.
12100002	The specified tokenID does not exist.
12100003	The specified permission does not exist or is not a user_grant permission.
12100006	The application specified by the tokenID is not allowed to be granted with the specified permission. Either the application is a sandbox or the tokenID is from a remote device.
12100007	The service is abnormal.

Example

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // For details about how to obtain the tokenID, see the description in the AtManager section.
let permissionFlags: number = 1;
atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => {
  console.info('grantUserGrantedPermission success');
}).catch((err: BusinessError): void => {
  console.error(`grantUserGrantedPermission fail, code: ${err.code}, message: ${err.message}`);
});

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
tokenID	number	Yes	ID of the target application, which can be obtained from the accessTokenId field of ApplicationInfo in BundleInfo of the application.
permissionName	Permissions	Yes	Permission to grant. For details, see Application Permissions.
permissionFlags	number	Yes	Permission flag. - 1: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission. - 2: No dialog box will be displayed the next time if the user denies authorization for the permission. The permission must be granted by the user in Settings. - 64: The permission is given just once if the user allows the permission only this time. The authorization is canceled after the application is switched to the background or exits.
callback	AsyncCallback<void>	Yes	Callback used to return the result. Grants the user_grant permission to the application. If the permission is granted successfully, err is undefined. Otherwise, err is an error object.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission "ohos.permission.GRANT_SENSITIVE_PERMISSIONS".
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001	Invalid parameter. The tokenID is 0, the permissionName exceeds 256 characters or is not declared in the module.json file, or the flags value is invalid.
12100002	The specified tokenID does not exist.
12100003	The specified permission does not exist or is not a user_grant permission.
12100006	The application specified by the tokenID is not allowed to be granted with the specified permission. Either the application is a sandbox or the tokenID is from a remote device.
12100007	The service is abnormal.

Example

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // For details about how to obtain the tokenID, see the description in the AtManager section.
let permissionFlags: number = 1;
atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => {
  if (err) {
    console.error(`grantUserGrantedPermission fail, code: ${err.code}, message: ${err.message}`);
  } else {
    console.info('grantUserGrantedPermission success');
  }
});

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
tokenID	number	Yes	ID of the target application, which can be obtained from the accessTokenId field of ApplicationInfo in BundleInfo of the application.
permissionName	Permissions	Yes	Permission to revoke. For details, see Application Permissions.
permissionFlags	number	Yes	Permission flag. - 1: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission. - 2: No dialog box will be displayed the next time if the user denies authorization for the permission. The permission must be granted by the user in Settings. - 64: The permission is given just once if the user allows the permission only this time. The authorization is canceled after the application is switched to the background or exits.

Return value

Type	Description
Promise<void>	Promise that returns no result.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission "ohos.permission.REVOKE_SENSITIVE_PERMISSIONS".
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001	Invalid parameter. The tokenID is 0, the permissionName exceeds 256 characters or is not declared in the module.json file, or the flags value is invalid.
12100002	The specified tokenID does not exist.
12100003	The specified permission does not exist or is not a user_grant permission.
12100006	The application specified by the tokenID is not allowed to be revoked with the specified permission. Either the application is a sandbox or the tokenID is from a remote device.
12100007	The service is abnormal.

Example

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // For details about how to obtain the tokenID, see the description in the AtManager section.
let permissionFlags: number = 1;
atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => {
  console.info('revokeUserGrantedPermission success');
}).catch((err: BusinessError): void => {
  console.error(`revokeUserGrantedPermission fail, code: ${err.code}, message: ${err.message}`);
});

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
tokenID	number	Yes	ID of the target application, which can be obtained from the accessTokenId field of ApplicationInfo in BundleInfo of the application.
permissionName	Permissions	Yes	Permission to revoke. For details, see Application Permissions.
permissionFlags	number	Yes	Permission flag. - 1: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission. - 2: No dialog box will be displayed the next time if the user denies authorization for the permission. The permission must be granted by the user in Settings. - 64: The permission is given just once if the user allows the permission only this time. The authorization is canceled after the application is switched to the background or exits.
callback	AsyncCallback<void>	Yes	Callback used to return the result. Revokes the user_grant permission of an application. If the permission is successfully revoked, err is undefined. Otherwise, err is an error object.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission "ohos.permission.REVOKE_SENSITIVE_PERMISSIONS".
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001	Invalid parameter. The tokenID is 0, the permissionName exceeds 256 characters or is not declared in the module.json file, or the flags value is invalid.
12100002	The specified tokenID does not exist.
12100003	The specified permission does not exist or is not a user_grant permission.
12100006	The application specified by the tokenID is not allowed to be revoked with the specified permission. Either the application is a sandbox or the tokenID is from a remote device.
12100007	The service is abnormal.

Example

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // For details about how to obtain the tokenID, see the description in the AtManager section.
let permissionFlags: number = 1;
atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => {
  if (err) {
    console.error(`revokeUserGrantedPermission fail, code: ${err.code}, message: ${err.message}`);
  } else {
    console.info('revokeUserGrantedPermission success');
  }
});

getPermissionFlags

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

Obtains the flag of the specified permission 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

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
tokenID	number	Yes	ID of the target application, which can be obtained from the accessTokenId field of ApplicationInfo in BundleInfo of the application.
permissionName	Permissions	Yes	Target permission. For details, see Application Permissions.

Return value

Type	Description
Promise<number>	Promise that returns the query result.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission specified below.
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001	Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters.
12100002	The specified tokenID does not exist.
12100003	The specified permission does not exist or is not declared in the module.json file.
12100006	The operation is not allowed. Either the application is a sandbox or the tokenID is from a remote device.
12100007	The service is abnormal.

Example

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // For details about how to obtain the tokenID, see the description in the AtManager section.
atManager.getPermissionFlags(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: number) => {
  console.info(`getPermissionFlags success, result: ${data}`);
}).catch((err: BusinessError): void => {
  console.error(`getPermissionFlags fail, code: ${err.code}, message: ${err.message}`);
});

setPermissionRequestToggleStatus¹²⁺

setPermissionRequestToggleStatus(permissionName: Permissions, status: PermissionRequestToggleStatus): Promise<void>

Sets the toggle state of a permission. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.DISABLE_PERMISSION_DIALOG

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
permissionName	Permissions	Yes	Permission to be set with the toggle state. For details, see Application Permissions.
status	PermissionRequestToggleStatus	Yes	Toggle state to set.

Return value

Type	Description
Promise<void>	Promise that returns no result.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission specified below.
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001	Invalid parameter. The permissionName exceeds 256 characters, the specified permission is not a user_grant permission, or the status value is invalid.
12100003	The specified permission does not exist.
12100007	The service is abnormal.
12100009	Common inner error. A database error occurs.

Example

import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager = abilityAccessCtrl.createAtManager();
let permission: Permissions = 'ohos.permission.CAMERA';

atManager.setPermissionRequestToggleStatus(permission, abilityAccessCtrl.PermissionRequestToggleStatus.CLOSED).then(() => {
  console.info('setPermissionRequestToggleStatus: set closed successful');
}).catch((err: BusinessError): void => {
  console.error(`setPermissionRequestToggleStatus fail, code: ${err.code}, message: ${err.message}`);
});

getPermissionRequestToggleStatus¹²⁺

getPermissionRequestToggleStatus(permissionName: Permissions): Promise<PermissionRequestToggleStatus>

Obtains the toggle state of a permission. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
permissionName	Permissions	Yes	Permission whose toggle state is to be obtained. For details, see Application Permissions.

Return value

Type	Description
Promise<PermissionRequestToggleStatus>	Promise that returns the status value of the pop-up window switch of a specified permission.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission specified below.
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001	Invalid parameter. The permissionName exceeds 256 characters, or the specified permission is not a user_grant permission.
12100003	The specified permission does not exist.
12100007	The service is abnormal.

Example

import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager = abilityAccessCtrl.createAtManager();
let permission: Permissions = 'ohos.permission.CAMERA';

atManager.getPermissionRequestToggleStatus(permission).then((res) => {
  if (res == abilityAccessCtrl.PermissionRequestToggleStatus.CLOSED) {
    console.info('getPermissionRequestToggleStatus: The toggle status is close');
  } else {
    console.info('getPermissionRequestToggleStatus: The toggle status is open');
  }
}).catch((err: BusinessError): void => {
  console.error(`getPermissionRequestToggleStatus fail, code: ${err.code}, message: ${err.message}`);
});

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

Type	Description
Promise<number>	Promise that returns the version obtained.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	Not System App. Interface caller is not a system app.

Example

import { abilityAccessCtrl } from '@kit.AbilityKit';

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

getPermissionsStatus¹²⁺

getPermissionsStatus(tokenID: number, permissionList: Array<Permissions>): Promise<Array<PermissionStatus>>

Obtains the status of the specified permissions. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
tokenID	number	Yes	ID of the target application, which can be obtained from the accessTokenId field of ApplicationInfo in BundleInfo of the application.
permissionList	Array<Permissions>	Yes	Permissions whose status is to be obtained. For details, see Application Permissions.

Return value

Type	Description
Promise<Array<PermissionStatus>>	Promise that returns the list of queried permission status.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission "ohos.permission.GET_SENSITIVE_PERMISSIONS".
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001	Invalid parameter. The tokenID is 0 or the permissionList is empty or exceeds the size limit.
12100002	The specified tokenID does not exist.
12100007	The service is abnormal.

Example

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // For details about how to obtain the tokenID, see the description in the AtManager section.
atManager.getPermissionsStatus(tokenID, ['ohos.permission.CAMERA']).then((data: Array<abilityAccessCtrl.PermissionStatus>) => {
  console.info(`getPermissionsStatus success, result: ${data}`);
}).catch((err: BusinessError): void => {
  console.error(`getPermissionsStatus fail, code: ${err.code}, message: ${err.message}`);
});

on⁹⁺

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

Subscribes to changes in the state of specified permissions for the given applications. This API uses an asynchronous callback to return the result.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is 'permissionStateChange', which indicates the permission state changes.
tokenIDList	Array<number>	Yes	List of application token IDs. If this parameter is not specified, this API will subscribe to the permission state changes of all applications.
permissionList	Array<Permissions>	Yes	List of target permissions. If this parameter is not specified, this API will subscribe to state changes of all permissions. For details about the permissions, see Application Permissions.
callback	Callback<PermissionStateChangeInfo>	Yes	Callback used to return the result. Callback for subscribing to the status change events of the specified tokenID and permission name.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission "ohos.permission.GET_SENSITIVE_PERMISSIONS".
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001	Invalid parameter. Possible causes: 1. The tokenIDList or permissionList exceeds the size limit; 2. The tokenIDs or permissionNames in the list are all invalid.
12100005	The registration time has exceeded the limit.
12100007	The service is abnormal.
12100008	Out of memory.

Example

import { abilityAccessCtrl, Permissions, bundleManager } from '@kit.AbilityKit';

try {
  let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
  let bundleInfo = bundleManager.getBundleInfoForSelfSync(bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION);
  let tokenIDList: Array<number> = [bundleInfo.appInfo.accessTokenId];
  let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC'];

  atManager.on('permissionStateChange', tokenIDList, permissionList, (data: abilityAccessCtrl.PermissionStateChangeInfo) => {
    console.info('receive permission state change');
    console.info(`data change: ${data.change}, tokenID: ${data.tokenID}, permission name: ${data.permissionName}`);
    });
} catch(err) {
  console.error(`catch errcode: ${err.code}, message: ${err.message}`);
}

off⁹⁺

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

Unsubscribes from changes in the state of the specified permissions for the token ID list and permission list. This API uses an asynchronous callback to return the result.

During unsubscribing, if no callback is passed, all callbacks in tokenIDList and permissionList are deleted in batches.

System API: This is a system API.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is 'permissionStateChange', which indicates the permission state changes.
tokenIDList	Array<number>	Yes	List of application token IDs. The value must be the same as that in on. If this parameter is not specified, this API will unsubscribe from the permission state changes of all applications.
permissionList	Array<Permissions>	Yes	List of target permissions. The value must be the same as that in on. If this parameter is not specified, this API will unsubscribe from state changes for all permissions. For details about the permissions, see Application Permissions.
callback	Callback<PermissionStateChangeInfo>	No	Callback used to return the result. Returns the object for unsubscribing from the status change events of the specified tokenID and permission name.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission "ohos.permission.GET_SENSITIVE_PERMISSIONS".
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001	Invalid parameter. The tokenIDList or permissionList is not in the listening list.
12100007	The service is abnormal.

Example

import { abilityAccessCtrl, Permissions, bundleManager } from '@kit.AbilityKit';

try {
  let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
  let bundleInfo = bundleManager.getBundleInfoForSelfSync(bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION);
  let tokenIDList: Array<number> = [bundleInfo.appInfo.accessTokenId];
  let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC'];
  atManager.off('permissionStateChange', tokenIDList, permissionList);
} catch(err) {
  console.error(`catch errcode: ${err.code}, message: ${err.message}`);
}

requestPermissionOnApplicationSetting¹⁸⁺

requestPermissionOnApplicationSetting(tokenID: number): Promise<void>

Starts the permission settings page for an application. This API uses a promise to return the result.

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
tokenID	number	Yes	ID of the target application, which can be obtained from the accessTokenId field of ApplicationInfo in BundleInfo of the application.

Return value

Type	Description
Promise<void>	Promise that returns no result.

Error codes

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

ID	Error Message
202	Not System App. Interface caller is not a system app.
12100002	The specified tokenID does not exist.
12100007	The service is abnormal.

Example

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // For details about how to obtain the tokenID, see the description in the AtManager section.
atManager.requestPermissionOnApplicationSetting(tokenID).then(() => {
  console.info('requestPermissionOnApplicationSetting success');
}).catch((err: BusinessError): void => {
  console.error(`requestPermissionOnApplicationSetting fail, code: ${err.code}, message: ${err.message}`);
});

grantPermission²¹⁺

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

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

System API: This is a system API.

Required permissions: ohos.permission.GRANT_SENSITIVE_PERMISSIONS

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
tokenID	number	Yes	ID of the target application, which can be obtained from the accessTokenId field of ApplicationInfo in BundleInfo of the application.
permissionName	Permissions	Yes	Permission to grant. For details, see Application Permissions.
permissionFlags	number	Yes	Permission flag. - 1: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission. - 2: No dialog box will be displayed the next time if the user denies authorization for the permission. The permission must be granted by the user in Settings. - 64: The permission is given just once if the user allows the permission only this time. The authorization is canceled after the application is switched to the background or exits.

Return value

Type	Description
Promise<void>	Promise that returns no result.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission "ohos.permission.GRANT_SENSITIVE_PERMISSIONS".
202	Not System App. Interface caller is not a system app.
12100001	Invalid parameter. The tokenID is 0, the permissionName exceeds 256 characters or is not declared in the module.json file, or the flags value is invalid.
12100002	The specified tokenID does not exist.
12100003	The specified permission does not exist.
12100006	The application specified by the tokenID is not allowed to be granted with the specified permission. Either the application is a sandbox or the tokenID is from a remote device.
12100007	The service is abnormal.
12100014	Unexpected permission. The specified permission is not a user_grant or manual_settings permission.

Example

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // For details about how to obtain the tokenID, see the description in the AtManager section.
let permissionFlags: number = 2;
atManager.grantPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => {
  console.info('grantPermission success');
}).catch((err: BusinessError): void => {
  console.error(`grantPermission fail, code: ${err.code}, message: ${err.message}`);
});

revokePermission²¹⁺

revokePermission(tokenID: number, permissionName: Permissions, permissionFlags: number, killProcess?: boolean): Promise<void>

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

System API: This is a system API.

Required permissions: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
tokenID	number	Yes	ID of the target application, which can be obtained from the accessTokenId field of ApplicationInfo in BundleInfo of the application.
permissionName	Permissions	Yes	Permission to revoke. For details, see Application Permissions.
permissionFlags	number	Yes	Permission flag. - 1: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission. - 2: No dialog box will be displayed the next time if the user denies authorization for the permission. The permission must be granted by the user in Settings. - 64: The permission is given just once if the user allows the permission only this time. The authorization is canceled after the application is switched to the background or exits.
killProcess	boolean	No	Whether to terminate the application process. - true: indicates to terminate the application process. - false: indicates not to terminate the application process. - The default value is true. Start version: 26.0.0

Return value

Type	Description
Promise<void>	Promise that returns no result.

Error codes

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

ID	Error Message
201	Permission denied. The interface invoker does not have permission "ohos.permission.REVOKE_SENSITIVE_PERMISSIONS".
202	Not a system application. The interface invoker is not a system application.
12100001	Invalid parameter. The token ID is 0, the permission name exceeds 256 characters or is not declared in the module.json file, or the value of flags is invalid.
12100002	The specified tokenID does not exist.
12100003	The specified permission does not exist.
12100006	The specified permission is not allowed to be revoked from the application specified by the tokenID. Either the application is a sandbox or the tokenID is from a remote device.
12100007	The service is abnormal.
12100014	Unexpected permission. The specified permission is not a user_grant or manual_settings permission.

Example

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // For details about how to obtain the tokenID, see the description in the AtManager section.
let permissionFlags: number = 2;
// Do not terminate the application process.
atManager.revokePermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, false).then(() => {
  console.info('revokePermission success, process not killed');
}).catch((err: BusinessError): void => {
  console.error(`revokePermission fail, code: ${err.code}, message: ${err.message}`);
});
// Terminate the application process (default behavior).
atManager.revokePermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => {
  console.info('revokePermission success');
}).catch((err: BusinessError): void => {
  console.error(`revokePermission fail, code: ${err.code}, message: ${err.message}`);
});

requestPermissionsFromUserWithWindowId²³⁺

requestPermissionsFromUserWithWindowId(context: Context, windowId: number, permissionList: Array<Permissions>): Promise<PermissionRequestResult>

Requests user authorization in a dialog box opened based on the window ID. This API uses a promise to return the result.

If the user rejects to grant permissions, the dialog box cannot be displayed again. If permission granting is required, the user can manually grant permissions on the Settings page or call requestPermissionOnSetting to display the permission settings dialog box for the user to grant permissions.

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context.
windowId	number	Yes	ID of an application window.
permissionList	Array<Permissions>	Yes	Permission to verify. For details about the permission, see Application Permissions.

Return value

Type	Description
Promise<PermissionRequestResult>	Promise that returns the result containing the API.

Error codes

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

ID	Error Message
12100001	Invalid parameter. windowId is invalid.
12100009	Common inner error. An error occurs when creating the popup window or obtaining the user operation result.

Example

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

For details about the process and example of applying for user authorization, see Requesting User Authorization.

import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
// Obtain the context within the component.
let context: Context = this.getUIContext().getHostContext() as Context;
let windowId = 0; // *Obtaining method* let windowId = window.findWindow(*window name*).getWindowProperties().id;
atManager.requestPermissionsFromUserWithWindowId(context, windowId, ['ohos.permission.CAMERA']).then((data: PermissionRequestResult) => {
  console.info(`requestPermissionsFromUserWithWindowId success, result: ${data}`);
  console.info('requestPermissionsFromUserWithWindowId data permissions:' + data.permissions);
  console.info('requestPermissionsFromUserWithWindowId data authResults:' + data.authResults);
  console.info('requestPermissionsFromUserWithWindowId data dialogShownResults:' + data.dialogShownResults);
  console.info('requestPermissionsFromUserWithWindowId data errorReasons:' + data.errorReasons);
}).catch((err: BusinessError): void => {
  console.error(`requestPermissionsFromUserWithWindowId fail, code: ${err.code}, message: ${err.message}`);
});

queryStatusByPermission

queryStatusByPermission(permissionList: Array<Permissions>): Promise<Array<PermissionStatusInfo>>

Queries all applications that have requested the permission and the permission status. This API uses a promise to return the result. Error code 12100015 is returned when the number of queried data records exceeds 50,000.

Start version: 26.0.0

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
permissionList	Array<Permissions>	Yes	List of permission names to be queried. This parameter cannot be empty and its length cannot exceed 1024.

Return value

Type	Description
Promise<Array<PermissionStatusInfo>>	Promise that returns the queried permission status information list.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission "ohos.permission.GET_SENSITIVE_PERMISSIONS".
202	Not system application. Interface caller is not a system application.
12100001	Invalid parameter. The permissionList is empty or exceeds the size limit.
12100003	The specified permission does not exist.
12100007	The service is abnormal.
12100015	The queried data exceeds the upper limit.

Example

import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let permissionList: Array<Permissions> = ['ohos.permission.CAMERA'];
atManager.queryStatusByPermission(permissionList).then((data: Array<abilityAccessCtrl.PermissionStatusInfo>) => {
  console.info('queryStatusByPermission success, data: ' + JSON.stringify(data));
}).catch((err: BusinessError): void => {
  console.error(`queryStatusByPermission fail, code: ${err.code}, message: ${err.message}`);
});

queryStatusByTokenID

queryStatusByTokenID(tokenIDList: Array<number>): Promise<Array<PermissionStatusInfo>>

Queries all permission statuses based on the application token ID list. This API uses a promise to return the result. Error code 12100015 is returned when the number of queried data records exceeds 50,000.

Start version: 26.0.0

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS

System capability: SystemCapability.Security.AccessToken

Parameters

Name	Type	Mandatory	Description
tokenIDList	Array<number>	Yes	List of application tokenID to be queried, which can be obtained from the accessTokenId field of ApplicationInfo in the BundleInfo of the application. This parameter cannot be empty and its length cannot exceed 1024.

Return value

Type	Description
Promise<Array<PermissionStatusInfo>>	Promise that returns the queried permission status information list.

Error codes

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

ID	Error Message
201	Permission denied. Interface caller does not have permission "ohos.permission.GET_SENSITIVE_PERMISSIONS".
202	Not system application. Interface caller is not a system application.
12100001	Invalid parameter. The tokenIDList is empty or exceeds the size limit.
12100002	The specified tokenID does not exist.
12100007	The service is abnormal.
12100015	The queried data exceeds the upper limit.

Example

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // For details about how to obtain the tokenID, see the description in the AtManager section.
let tokenIDList: Array<number> = [tokenID];
atManager.queryStatusByTokenID(tokenIDList).then((data: Array<abilityAccessCtrl.PermissionStatusInfo>) => {
  console.info('queryStatusByTokenID success, data: ' + JSON.stringify(data));
}).catch((err: BusinessError): void => {
  console.error(`queryStatusByTokenID fail, code: ${err.code}, message: ${err.message}`);
});

PermissionStatusInfo

Indicates the permission status.

Start version: 26.0.0

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.AccessToken

Name	Type	Read-Only	Optional	Description
tokenID	number	No	No	Application ID.
permissionName	Permissions	No	No	Permission name.
grantStatus	GrantStatus	No	No	Permission authorization status.
grantFlags	number	No	No	Permission flag. - 1: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission. - 2: No dialog box will be displayed the next time if the user denies authorization for the permission. The permission must be granted by the user in Settings. - 64: The permission is given just once if the user allows the permission only this time. The authorization is canceled after the application is switched to the background or exits.
grantTimestamp	number	No	Yes	Timestamp of the authorization status change, in ms.

PermissionRequestToggleStatus¹²⁺

Enumerates the permission toggle states.

System API: This is a system API.

System capability: SystemCapability.Security.AccessToken

Name	Value	Description
CLOSED	0	The permission is toggled off.
OPEN	1	The permission is toggled on.