1# @ohos.abilityAccessCtrl (Application Access Control) (System API) 2 3The **abilityAccessCtrl** module provides APIs for application permission management, including authentication, authorization, and revocation. 4 5> **NOTE** 6> 7> - 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. 8> - This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.abilityAccessCtrl (Application Access Control)](js-apis-abilityAccessCtrl.md). 9 10## Modules to Import 11 12```ts 13import abilityAccessCtrl from '@ohos.abilityAccessCtrl' 14``` 15 16## AtManager 17 18Provides APIs for application access control. 19 20### grantUserGrantedPermission 21 22grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void> 23 24Grants a user_grant permission to an application. This API uses a promise to return the result. 25 26**System API**: This is a system API. 27 28**Required permissions**: ohos.permission.GRANT_SENSITIVE_PERMISSIONS (available only to system applications) 29 30**System capability**: SystemCapability.Security.AccessToken 31 32**Parameters** 33 34| Name | Type | Mandatory| Description | 35| --------- | ------------------- | ---- | ------------------------------------------------------------ | 36| tokenID | number | Yes | Application token ID, which can be obtained from [ApplicationInfo](js-apis-bundleManager-applicationInfo.md). | 37| permissionName | Permissions | Yes | Permission to grant. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 38| permissionFlags | number | Yes | Permission flag.<br>- **1**: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission.<br>- **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**.<br>- **64**: The permission is granted to the user only this time. The authorization is revoked after the application switches to the background or exits.| 39 40**Return value** 41 42| Type | Description | 43| :------------ | :---------------------------------- | 44| Promise<void> | Promise that returns no value.| 45 46**Error codes** 47 48For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 49 50| ID| Error Message| 51| -------- | -------- | 52| 12100001 | The parameter is invalid. The tokenID is 0, the permissionName exceeds 256 bytes, or the flags value is invalid.| 53| 12100002 | The specified tokenID does not exist. | 54| 12100003 | The specified permission does not exist. | 55| 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. | 56| 12100007 | Service is abnormal. | 57 58**Example** 59 60```ts 61import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 62import { BusinessError } from '@ohos.base'; 63 64let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 65let 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. 66let permissionFlags: number = 1; 67try { 68 atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => { 69 console.log('grantUserGrantedPermission success'); 70 }).catch((err: BusinessError) => { 71 console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`); 72 }); 73} catch(err) { 74 console.log(`catch err->${JSON.stringify(err)}`); 75} 76``` 77 78### grantUserGrantedPermission 79 80grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void 81 82Grants a user_grant permission to an application. This API uses an asynchronous callback to return the result. 83 84**System API**: This is a system API. 85 86**Required permissions**: ohos.permission.GRANT_SENSITIVE_PERMISSIONS (available only to system applications) 87 88**System capability**: SystemCapability.Security.AccessToken 89 90**Parameters** 91 92| Name | Type | Mandatory| Description | 93| --------- | ------------------- | ---- | ------------------------------------------------------------ | 94| tokenID | number | Yes | Application token ID, which can be obtained from [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 95| permissionName | Permissions | Yes | Permission to grant. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 96| permissionFlags | number | Yes | Permission flag.<br>- **1**: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission.<br>- **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**.<br>- **64**: The permission is granted to the user only this time. The authorization is revoked after the application switches to the background or exits.| 97| callback | AsyncCallback<void> | Yes| Grants a user_grant permission to an application. If the permission is granted, **err** is **undefined**. Otherwise, **err** is an error object.| 98 99**Error codes** 100 101For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 102 103| ID| Error Message| 104| -------- | -------- | 105| 12100001 | The parameter is invalid. The tokenID is 0, the permissionName exceeds 256 bytes, or the flags value is invalid.| 106| 12100002 | The specified tokenID does not exist. | 107| 12100003 | The specified permission does not exist. | 108| 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. | 109| 12100007 | Service is abnormal. | 110 111**Example** 112 113```ts 114import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 115import { BusinessError } from '@ohos.base'; 116 117let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 118let 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. 119let permissionFlags: number = 1; 120try { 121 atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => { 122 if (err) { 123 console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`); 124 } else { 125 console.log('grantUserGrantedPermission success'); 126 } 127 }); 128} catch(err) { 129 console.log(`catch err->${JSON.stringify(err)}`); 130} 131``` 132 133### revokeUserGrantedPermission 134 135revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void> 136 137Revokes a user_grant permission from an application. This API uses a promise to return the result. 138 139**System API**: This is a system API. 140 141**Required permissions**: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications) 142 143**System capability**: SystemCapability.Security.AccessToken 144 145**Parameters** 146 147| Name | Type | Mandatory| Description | 148| --------- | ------------------- | ---- | ------------------------------------------------------------ | 149| tokenID | number | Yes | Application token ID, which can be obtained from [ApplicationInfo](js-apis-bundleManager-applicationInfo.md). | 150| permissionName | Permissions | Yes | Permission to revoke. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 151| permissionFlags | number | Yes | Permission flag.<br>- **1**: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission.<br>- **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**.<br>- **64**: The permission is granted to the user only this time. The authorization is revoked after the application switches to the background or exits.| 152 153**Return value** 154 155| Type | Description | 156| :------------ | :---------------------------------- | 157| Promise<void> | Promise that returns no value.| 158 159**Error codes** 160 161For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 162 163| ID| Error Message| 164| -------- | -------- | 165| 12100001 | The parameter is invalid. The tokenID is 0, the permissionName exceeds 256 bytes, or the flags value is invalid.| 166| 12100002 | The specified tokenID does not exist. | 167| 12100003 | The specified permission does not exist. | 168| 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. | 169| 12100007 | Service is abnormal. | 170 171**Example** 172 173```ts 174import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 175import { BusinessError } from '@ohos.base'; 176 177let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 178let 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. 179let permissionFlags: number = 1; 180try { 181 atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => { 182 console.log('revokeUserGrantedPermission success'); 183 }).catch((err: BusinessError) => { 184 console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`); 185 }); 186} catch(err) { 187 console.log(`catch err->${JSON.stringify(err)}`); 188} 189``` 190 191### revokeUserGrantedPermission 192 193revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void 194 195Revokes a user_grant permission from an application. This API uses an asynchronous callback to return the result. 196 197**System API**: This is a system API. 198 199**Required permissions**: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications) 200 201**System capability**: SystemCapability.Security.AccessToken 202 203**Parameters** 204 205| Name | Type | Mandatory| Description | 206| --------- | ------------------- | ---- | ------------------------------------------------------------ | 207| tokenID | number | Yes | Application token ID, which can be obtained from [ApplicationInfo](js-apis-bundleManager-applicationInfo.md). | 208| permissionName | Permissions | Yes | Permission to revoke. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 209| permissionFlags | number | Yes | Permission flag.<br>- **1**: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission.<br>- **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**.<br>- **64**: The permission is granted to the user only this time. The authorization is revoked after the application switches to the background or exits.| 210| callback | AsyncCallback<void> | Yes| Callback invoked to return the result. If the permission is revoked, **err** is **undefined**. Otherwise, **err** is an error object.| 211 212**Error codes** 213 214For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 215 216| ID| Error Message| 217| -------- | -------- | 218| 12100001 | The parameter is invalid. The tokenID is 0, the permissionName exceeds 256 bytes, or the flags value is invalid.| 219| 12100002 | The specified tokenID does not exist. | 220| 12100003 | The specified permission does not exist. | 221| 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. | 222| 12100007 | Service is abnormal. | 223 224**Example** 225 226```ts 227import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 228import { BusinessError } from '@ohos.base'; 229 230let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 231let 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. 232let permissionFlags: number = 1; 233try { 234 atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => { 235 if (err) { 236 console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`); 237 } else { 238 console.log('revokeUserGrantedPermission success'); 239 } 240 }); 241} catch(err) { 242 console.log(`catch err->${JSON.stringify(err)}`); 243} 244``` 245 246### getPermissionFlags 247 248getPermissionFlags(tokenID: number, permissionName: Permissions): Promise<number> 249 250Obtains the permission flag of an application. This API uses a promise to return the result. 251 252**System API**: This is a system API. 253 254**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS, ohos.permission.GRANT_SENSITIVE_PERMISSIONS, or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications) 255 256**System capability**: SystemCapability.Security.AccessToken 257 258**Parameters** 259 260| Name | Type | Mandatory| Description | 261| --------- | ------------------- | ---- | ------------------------------------------------------------ | 262| tokenID | number | Yes | Application token ID, which can be obtained from [ApplicationInfo](js-apis-bundleManager-applicationInfo.md). | 263| permissionName | Permissions | Yes | Permission whose flag is to be obtained. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 264 265**Return value** 266 267| Type | Description | 268| :------------ | :---------------------------------- | 269| Promise<number> | Promise used to return the permission flag obtained. | 270 271**Error codes** 272 273For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 274 275| ID| Error Message| 276| -------- | -------- | 277| 12100001 | The parameter is invalid. The tokenID is 0, or permissionName exceeds 256 bytes.| 278| 12100002 | The specified tokenID does not exist. | 279| 12100003 | The specified permission does not exist. | 280| 12100006 | The operation is not allowed. Either the application is a sandbox or the tokenID is from a remote device. | 281| 12100007 | Service is abnormal. | 282 283**Example** 284 285```ts 286import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 287import { BusinessError } from '@ohos.base'; 288 289let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 290let 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. 291try { 292 atManager.getPermissionFlags(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: number) => { 293 console.log(`getPermissionFlags success, data->${JSON.stringify(data)}`); 294 }).catch((err: BusinessError) => { 295 console.log(`getPermissionFlags fail, err->${JSON.stringify(err)}`); 296 }); 297} catch(err) { 298 console.log(`catch err->${JSON.stringify(err)}`); 299} 300``` 301 302### getVersion<sup>9+</sup> 303 304getVersion(): Promise<number> 305 306Obtains the data version of the permission management. This API uses a promise to return the result. 307 308**System API**: This is a system API. 309 310**System capability**: SystemCapability.Security.AccessToken 311 312**Return value** 313 314| Type | Description | 315| :------------ | :---------------------------------- | 316| Promise<number> | Promise used to return the version obtained.| 317 318**Example** 319 320```ts 321import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 322 323let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 324let promise = atManager.getVersion(); 325promise.then((data: number) => { 326 console.log(`promise: data->${JSON.stringify(data)}`); 327}); 328``` 329 330### on<sup>9+</sup> 331 332on(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback: Callback<PermissionStateChangeInfo>): void 333 334Subscribes to permission state changes of the specified applications and permissions. 335 336Multiple callbacks can be registered for the specified **tokenIDList** and **permissionList**. 337 338If **tokenIDList** and **permissionList** have common values with the **tokenIDList** and **permissionList** of a callback registered, **callback** must be different. 339 340**System API**: This is a system API. 341 342**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS (available only to system applications) 343 344**System capability**: SystemCapability.Security.AccessToken 345 346**Parameters** 347 348| Name | Type | Mandatory| Description | 349| ------------------ | --------------------- | ---- | ------------------------------------------------------------ | 350| type | string | Yes | Event type. The value is **'permissionStateChange'**, which indicates the permission grant state changes. | 351| 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.| 352| 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](../../security/AccessToken/permissions-for-all.md).| 353| callback | Callback<[PermissionStateChangeInfo](#permissionstatechangeinfo9)> | Yes| Callback invoked to return the permission grant state change.| 354 355**Error codes** 356 357For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 358 359| ID| Error Message| 360| -------- | -------- | 361| 12100001 | The parameter is invalid. The tokenID is 0, or permissionName exceeds 256 bytes.| 362| 12100004 | The interface is called repeatedly with the same input. | 363| 12100005 | The registration time has exceeded the limitation. | 364| 12100007 | Service is abnormal. | 365| 12100008 | Out of memory. | 366 367**Example** 368 369```ts 370import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; 371import bundleManager from '@ohos.bundle.bundleManager'; 372 373let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 374let appInfo: bundleManager.ApplicationInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100); 375let tokenIDList: Array<number> = [appInfo.accessTokenId]; 376let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC']; 377try { 378 atManager.on('permissionStateChange', tokenIDList, permissionList, (data: abilityAccessCtrl.PermissionStateChangeInfo) => { 379 console.debug('receive permission state change, data:' + JSON.stringify(data)); 380 }); 381} catch(err) { 382 console.log(`catch err->${JSON.stringify(err)}`); 383} 384``` 385 386### off<sup>9+</sup> 387 388off(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback?: Callback<PermissionStateChangeInfo>): void 389 390Unsubscribes from permission grant state changes of the specified applications and permissions. This API uses a callback to return the result. 391 392If no callback is passed in **atManager.off**, all callbacks for **tokenIDList** and **permissionList** will be unregistered. 393 394**System API**: This is a system API. 395 396**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS (available only to system applications) 397 398**System capability**: SystemCapability.Security.AccessToken 399 400**Parameters** 401 402| Name | Type | Mandatory| Description | 403| ------------------ | --------------------- | ---- | ------------------------------------------------------------ | 404| type | string | Yes | Event type. The value is **'permissionStateChange'**, which indicates the permission grant state changes. | 405| tokenIDList | Array<number> | Yes | List of application token IDs. The value must be the same as that passed in **on()**. If this parameter is left empty, this API unsubscribes from the permission grant state changes of all applications.| 406| permissionList | Array<Permissions> | Yes | List of permissions. The value must be the same as that of **on()**. If this parameter is left empty, this API unsubscribes from state changes of all permissions. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 407| callback | Callback<[PermissionStateChangeInfo](#permissionstatechangeinfo9)> | No| Callback for the permission grant state change.| 408 409**Error codes** 410 411For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 412 413| ID| Error Message| 414| -------- | -------- | 415| 12100001 | The parameter is invalid. The tokenIDs or permissionNames in the list are all invalid. | 416| 12100004 | The interface is not used together with 'on'. | 417| 12100007 | Service is abnormal. | 418| 12100008 | Out of memory. | 419 420**Example** 421 422```ts 423import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; 424import bundleManager from '@ohos.bundle.bundleManager'; 425 426let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 427let appInfo: bundleManager.ApplicationInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100); 428let tokenIDList: Array<number> = [appInfo.accessTokenId]; 429let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC']; 430try { 431 atManager.off('permissionStateChange', tokenIDList, permissionList); 432} catch(err) { 433 console.log(`catch err->${JSON.stringify(err)}`); 434} 435``` 436 437### PermissionStateChangeType<sup>9+</sup> 438 439Enumerates the operations that trigger permission grant state changes. 440 441**System API**: This is a system API. 442 443**System capability**: SystemCapability.Security.AccessToken 444 445| Name | Value| Description | 446| ----------------------- | ------ | ----------------- | 447| PERMISSION_REVOKED_OPER | 0 | Operation to revoke the permission.| 448| PERMISSION_GRANTED_OPER | 1 | Operation to grant the permission.| 449 450### PermissionStateChangeInfo<sup>9+</sup> 451 452Defines detailed information about the permission grant state change. 453 454**System API**: This is a system API. 455 456**System capability**: SystemCapability.Security.AccessToken 457 458| Name | Type | Readable| Writable| Description | 459| -------------- | ------------------------- | ---- | ---- | ------------------ | 460| change | [PermissionStateChangeType](#permissionstatechangetype9) | Yes | No | Operation that triggers the permission grant state change. | 461| tokenID | number | Yes | No | Application token ID.| 462| permissionName | Permissions | Yes | No | Permission whose grant state changes. For details about the permissions, see the [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md). | 463 464<!--no_check-->