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

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

Name Type Mandatory Description
tokenID number Yes Application token ID, which is the value of accessTokenId in ApplicationInfo.
permissionName Permissions Yes Permission to grant. For details about the permissions, see Permissions for All Applications.
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 granted to the user only this time. The authorization is revoked after the application switches to the background or exits.

Return value

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

Error codes

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

ID Error Message
201 Permission denied. Interface caller does not have permission.
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, 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.

Example

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

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;
atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => {
  console.log('grantUserGrantedPermission success');
}).catch((err: BusinessError) => {
  console.error(`grantUserGrantedPermission fail, 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

Name Type Mandatory Description
tokenID number Yes Application token ID, which is the value of accessTokenId in ApplicationInfo.
permissionName Permissions Yes Permission to grant. For details about the permissions, see Permissions for All Applications.
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 granted to the user only this time. The authorization is revoked after the application switches to the background or exits.
callback AsyncCallback<void> Yes Callback used to return the result. If the permission is granted, err is undefined. Otherwise, err is an error object.

Error codes

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

ID Error Message
201 Permission denied. Interface caller does not have permission.
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, 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.

Example

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

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;
atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => {
  if (err) {
    console.error(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`);
  } else {
    console.log('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 (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Name Type Mandatory Description
tokenID number Yes Application token ID, which is the value of accessTokenId in ApplicationInfo.
permissionName Permissions Yes Permission to revoke. For details, see Permissions for All Applications.
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 granted to the user only this time. The authorization is revoked after the application switches to the background or exits.

Return value

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

Error codes

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

ID Error Message
201 Permission denied. Interface caller does not have permission.
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, 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 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; // 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;
atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => {
  console.log('revokeUserGrantedPermission success');
}).catch((err: BusinessError) => {
  console.error(`revokeUserGrantedPermission fail, 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

Name Type Mandatory Description
tokenID number Yes Application token ID, which is the value of accessTokenId in ApplicationInfo.
permissionName Permissions Yes Permission to revoke. For details, see Permissions for All Applications.
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 granted to the user only this time. The authorization is revoked after the application switches to the background or exits.
callback AsyncCallback<void> Yes Callback used to return the result. If the permission is revoked, err is undefined. Otherwise, err is an error object.

Error codes

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

ID Error Message
201 Permission denied. Interface caller does not have permission.
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, 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 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; // 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;
atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => {
  if (err) {
    console.error(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`);
  } else {
    console.log('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 (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Name Type Mandatory Description
tokenID number Yes Application token ID, which is the value of accessTokenId in ApplicationInfo.
permissionName Permissions Yes Permission whose flag is to be obtained. For details, see Permissions for All Applications.

Return value

Type Description
Promise<number> Promise used to return the flag obtained.

Error codes

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

ID Error Message
201 Permission denied. Interface caller does not have permission.
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.
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; // 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.
atManager.getPermissionFlags(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: number) => {
  console.log(`getPermissionFlags success, data->${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`getPermissionFlags fail, err->${JSON.stringify(err)}`);
});

setPermissionRequestToggleStatus12+

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 Permissions for All Applications.
status PermissionRequestToggleStatus Yes Toggle state to set.

Return value

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

Error codes

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

ID Error Message
201 Permission denied. Interface caller does not have permission.
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 status value is invalid.
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.setPermissionRequestToggleStatus(permission, abilityAccessCtrl.PermissionRequestToggleStatus.CLOSED).then((err) => {
  console.info('toggle_status: Set closed successful');
}).catch((err: BusinessError) => {
  console.error('toggle_status: Code is ${err.code}, message is ${err.message}');
});

getPermissionRequestToggleStatus12+

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 Permissions for All Applications.

Return value

Type Description
Promise<PermissionRequestToggleStatus> Promise used to return the toggle state obtained.

Error codes

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

ID Error Message
201 Permission denied. Interface caller does not have permission.
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.
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('toggle_status: The toggle status is close');
  } else {
    console.info('toggle_status: The toggle status is open');
  }
}).catch((err: BusinessError) => {
console.error('toggle_status: Code is ${err.code}, message is ${err.message}');
});

getVersion9+

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 used to return the version obtained.
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.log(`promise: data->${JSON.stringify(data)}`);
});

getPermissionsStatus12+

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 (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Name Type Mandatory Description
tokenID number Yes Application token ID, which is the value of accessTokenId in ApplicationInfo.
permissionList Array<Permissions> Yes Permissions whose status is to be obtained. For details, see Permissions for All Applications.

Return value

Type Description
Promise<Array<PermissionStatus>> Promise used to return the permission statuses obtained.

Error codes

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

ID Error Message
201 Permission denied. Interface caller does not have permission.
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.
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; // 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.
atManager.getPermissionsStatus(tokenID, ['ohos.permission.CAMERA']).then((data: Array<abilityAccessCtrl.PermissionStatus>) => {
  console.log(`getPermissionsStatus success, data->${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`getPermissionsStatus fail, err->${JSON.stringify(err)}`);
});

on9+

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

Name Type Mandatory Description
type string Yes Event type. The value is 'permissionStateChange', which indicates the permission grant state changes.
tokenIDList Array<number> Yes List of application token IDs. If this parameter is left empty, this API subscribes to the permission grant state changes of all applications.
permissionList Array<Permissions> Yes List of permissions to be subscribed to. If this parameter is left empty, this API subscribes to state changes of all permissions. For details about the permissions, see Permissions for All Applications.
callback Callback<PermissionStateChangeInfo> Yes Callback invoked to return the permission grant state change.

Error codes

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

ID Error Message
201 Permission denied. Interface caller does not have permission.
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.
12100004 The API is used repeatedly with the same input.
12100005 The registration time has exceeded the limitation.
12100007 The service is abnormal.
12100008 Out of memory.

Example

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

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.error(`catch err->${JSON.stringify(err)}`);
}

off9+

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

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

If callback is not specified, this API will unregister all callbacks for tokenIDList and permissionList.

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

Name Type Mandatory Description
type string Yes Event type. The value is 'permissionStateChange', which indicates the permission grant 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 to unregister.

Error codes

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

ID Error Message
201 Permission denied. Interface caller does not have permission.
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 tokenIDs or permissionNames in the list are all invalid.
12100004 The API is not used in pair with 'on'.
12100007 The service is abnormal.
12100008 Out of memory.

Example

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

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.error(`catch err->${JSON.stringify(err)}`);
}

PermissionStateChangeType9+

Enumerates the operations that trigger permission grant state changes.

System API: This is a system API.

System capability: SystemCapability.Security.AccessToken

Name Value Description
PERMISSION_REVOKED_OPER 0 Operation to revoke the permission.
PERMISSION_GRANTED_OPER 1 Operation to grant the permission.

PermissionRequestToggleStatus12+

Enumerates the permission toggle states.

System capability: SystemCapability.Security.AccessToken

Name Value Description
CLOSED 0 The permission request toggle is disabled.
OPEN 1 The permission request toggle is enabled.

PermissionStateChangeInfo9+

Defines detailed information about the permission grant state change.

System API: This is a system API.

System capability: SystemCapability.Security.AccessToken

Name Type Read Only Mandatory Description
change PermissionStateChangeType Yes Yes Operation that triggers the permission grant state change.
tokenID number Yes Yes Application token ID, which is the value of accessTokenId in ApplicationInfo.
permissionName Permissions Yes Yes Permission whose grant state changes. For details about the permissions, see Permissions for All Applications.

PermissionStatus12+

Enumerates the permission states.

System API: This is a system API.

System capability: SystemCapability.Security.AccessToken

Name Value Description
DENIED -1 The permission is not granted.
GRANTED 0 The permission is granted.
NOT_DETERMINED 1 The permission state is not determined.
INVALID 2 The permission is invalid.
RESTRICTED 3 The permission is restricted.