1# @ohos.abilityAccessCtrl (Application Access Control) 2 3The **abilityAccessCtrl** module provides APIs for application permission management, including authentication, authorization, and revocation. 4 5> **NOTE** 6> 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. 7 8## Modules to Import 9 10```ts 11import { abilityAccessCtrl } from '@kit.AbilityKit' 12``` 13 14## abilityAccessCtrl.createAtManager 15 16createAtManager(): AtManager 17 18Creates an **AtManager** instance, which is used for application access control. 19 20**Atomic service API**: This API can be used in atomic services since API version 11. 21 22**System capability**: SystemCapability.Security.AccessToken 23 24 25**Return value** 26 27| Type| Description| 28| -------- | -------- | 29| [AtManager](#atmanager) | **AtManager** instance created.| 30 31**Example** 32 33```ts 34let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 35``` 36 37## AtManager 38 39Provides APIs for application access control. 40 41### checkAccessToken<sup>9+</sup> 42 43checkAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus> 44 45Checks whether a permission is granted to an application. This API uses a promise to return the result. 46 47**Atomic service API**: This API can be used in atomic services since API version 11. 48 49**System capability**: SystemCapability.Security.AccessToken 50 51**Parameters** 52 53| Name | Type | Mandatory| Description | 54| -------- | ------------------- | ---- | ------------------------------------------ | 55| tokenID | number | Yes | Application token ID, which is the value of **accessTokenId** in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 56| permissionName | Permissions | Yes | Permission to check. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 57 58**Return value** 59 60| Type | Description | 61| :------------ | :---------------------------------- | 62| Promise<[GrantStatus](#grantstatus)> | Promise used to return the permission grant state.| 63 64**Error codes** 65 66For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 67 68| ID| Error Message| 69| -------- | -------- | 70| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 71| 12100001 | Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters. | 72 73**Example** 74 75```ts 76import { abilityAccessCtrl } from '@kit.AbilityKit'; 77import { BusinessError } from '@kit.BasicServicesKit'; 78 79let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 80let 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. 81atManager.checkAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => { 82 console.log(`checkAccessToken success, data->${JSON.stringify(data)}`); 83}).catch((err: BusinessError) => { 84 console.error(`checkAccessToken fail, err->${JSON.stringify(err)}`); 85}); 86``` 87 88### verifyAccessTokenSync<sup>9+</sup> 89 90verifyAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus 91 92Verifies whether a permission is granted to an application. This API returns the result synchronously. 93 94**System capability**: SystemCapability.Security.AccessToken 95 96**Parameters** 97 98| Name | Type | Mandatory| Description | 99| -------- | ------------------- | ---- | ------------------------------------------ | 100| tokenID | number | Yes | Application token ID, which is the value of **accessTokenId** in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 101| permissionName | Permissions | Yes | Permission to verify. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 102 103**Return value** 104 105| Type | Description | 106| :------------ | :---------------------------------- | 107| [GrantStatus](#grantstatus) | Permission grant state.| 108 109**Error codes** 110 111For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 112 113| ID| Error Message| 114| -------- | -------- | 115| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 116| 12100001 | Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters. | 117 118**Example** 119 120```ts 121import { abilityAccessCtrl } from '@kit.AbilityKit'; 122 123let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 124let 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. 125try { 126 let data: abilityAccessCtrl.GrantStatus = atManager.verifyAccessTokenSync(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'); 127 console.log(`data->${JSON.stringify(data)}`); 128} catch(err) { 129 console.error(`catch err->${JSON.stringify(err)}`); 130} 131``` 132 133### verifyAccessToken<sup>9+</sup> 134 135verifyAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus> 136 137Verifies whether a permission is granted to an application. This API uses a promise to return the result. 138 139> **NOTE** 140> 141> You are advised to use [checkAccessToken](#checkaccesstoken9). 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 is the value of **accessTokenId** in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 150| permissionName | Permissions | Yes | Permission to verify. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 151 152**Return value** 153 154| Type | Description | 155| :------------ | :---------------------------------- | 156| Promise<[GrantStatus](#grantstatus)> | Promise used to return the permission grant state.| 157 158**Example** 159 160```ts 161import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit'; 162import { BusinessError } from '@kit.BasicServicesKit'; 163 164let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 165let 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. 166let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'; 167atManager.verifyAccessToken(tokenID, permissionName).then((data: abilityAccessCtrl.GrantStatus) => { 168 console.log(`promise: data->${JSON.stringify(data)}`); 169}).catch((err: BusinessError) => { 170 console.error(`verifyAccessToken fail, err->${JSON.stringify(err)}`); 171}); 172``` 173 174### requestPermissionsFromUser<sup>9+</sup> 175 176requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>, requestCallback: AsyncCallback<PermissionRequestResult>): void 177 178Requests user authorization in a dialog box opened by a <!--RP1-->UIAbility<!--RP1End-->. This API uses an asynchronous callback to return the result. 179 180If the user rejects to grant the permission, the authorization dialog box cannot be displayed again. If required, the user can manually grant the permission on the **Settings** page. 181 182> **NOTE** 183> 184> Only <!--RP1-->UIAbility<!--RP1End--> is supported. 185 186**Atomic service API**: This API can be used in atomic services since API version 12. 187 188**Model restriction**: This API can be used only in the stage model. 189 190**System capability**: SystemCapability.Security.AccessToken 191 192**Parameters** 193 194| Name| Type| Mandatory| Description| 195| -------- | -------- | -------- | -------- | 196| context | [Context](js-apis-inner-application-context.md) | Yes| Context of the <!--RP1-->UIAbility<!--RP1End--> that requests the permission.| 197| permissionList | Array<Permissions> | Yes| Permissions to request. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 198| requestCallback | AsyncCallback<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Yes| Callback invoked to return the result.| 199 200**Error codes** 201 202For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 203 204| ID| Error Message| 205| -------- | -------- | 206| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 207| 12100001 | Invalid parameter. The context is invalid when it does not belong to the application itself. | 208 209**Example** 210For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 211 212```ts 213import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit'; 214import { BusinessError } from '@kit.BasicServicesKit'; 215 216let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 217let context: Context = getContext(this) as common.UIAbilityContext; 218atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA'], (err: BusinessError, data: PermissionRequestResult) => { 219 if (err) { 220 console.error(`requestPermissionsFromUser fail, err->${JSON.stringify(err)}`); 221 } else { 222 console.info('data:' + JSON.stringify(data)); 223 console.info('data permissions:' + data.permissions); 224 console.info('data authResults:' + data.authResults); 225 console.info('data dialogShownResults:' + data.dialogShownResults); 226 } 227}); 228``` 229 230### requestPermissionsFromUser<sup>9+</sup> 231 232requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>): Promise<PermissionRequestResult> 233 234Requests user authorization in a dialog box opened by a <!--RP1-->UIAbility<!--RP1End-->. This API uses a promise to return the result. 235 236If the user rejects to grant the permission, the authorization dialog box cannot be displayed again. If required, the user can manually grant the permission on the **Settings** page. 237 238> **NOTE** 239> 240> Only <!--RP1-->UIAbility<!--RP1End--> is supported. 241 242**Atomic service API**: This API can be used in atomic services since API version 11. 243 244**Model restriction**: This API can be used only in the stage model. 245 246**System capability**: SystemCapability.Security.AccessToken 247 248**Parameters** 249 250| Name| Type| Mandatory| Description| 251| -------- | -------- | -------- | -------- | 252| context | [Context](js-apis-inner-application-context.md) | Yes| Context of the <!--RP1-->UIAbility<!--RP1End--> that requests the permission.| 253| permissionList | Array<Permissions> | Yes| Permissions to request. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 254 255**Return value** 256 257| Type| Description| 258| -------- | -------- | 259| Promise<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Promise used to return the result.| 260 261**Error codes** 262 263For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 264 265| ID| Error Message| 266| -------- | -------- | 267| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 268| 12100001 | Invalid parameter. The context is invalid when it does not belong to the application itself. | 269 270**Example** 271For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 272 273```ts 274import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit'; 275import { BusinessError } from '@kit.BasicServicesKit'; 276 277let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 278let context: Context = getContext(this) as common.UIAbilityContext; 279atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA']).then((data: PermissionRequestResult) => { 280 console.info('data:' + JSON.stringify(data)); 281 console.info('data permissions:' + data.permissions); 282 console.info('data authResults:' + data.authResults); 283 console.info('data dialogShownResults:' + data.dialogShownResults); 284}).catch((err: BusinessError) => { 285 console.error('data:' + JSON.stringify(err)); 286}); 287``` 288 289### verifyAccessToken<sup>(deprecated)</sup> 290 291verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> 292 293Verifies whether a permission is granted to an application. This API uses a promise to return the result. 294 295> **NOTE** 296> 297> This API is no longer maintained since API version 9. Use [checkAccessToken](#checkaccesstoken9) instead. 298 299**System capability**: SystemCapability.Security.AccessToken 300 301**Parameters** 302 303| Name | Type | Mandatory| Description | 304| -------- | ------------------- | ---- | ------------------------------------------ | 305| tokenID | number | Yes | Application token ID, which is the value of **accessTokenId** in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 306| permissionName | string | Yes | Permission to verify. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 307 308**Return value** 309 310| Type | Description | 311| :------------ | :---------------------------------- | 312| Promise<[GrantStatus](#grantstatus)> | Promise used to return the permission grant state.| 313 314**Example** 315 316```ts 317import { abilityAccessCtrl } from '@kit.AbilityKit'; 318import { BusinessError } from '@kit.BasicServicesKit'; 319 320let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 321let 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. 322atManager.verifyAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => { 323 console.log(`promise: data->${JSON.stringify(data)}`); 324}).catch((err: BusinessError) => { 325 console.error(`verifyAccessToken fail, err->${JSON.stringify(err)}`); 326}); 327``` 328 329### checkAccessTokenSync<sup>10+</sup> 330 331checkAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus 332 333Checks whether a permission is granted to an application. This API returns the result synchronously. 334 335**Atomic service API**: This API can be used in atomic services since API version 11. 336 337**System capability**: SystemCapability.Security.AccessToken 338 339**Parameters** 340 341| Name | Type | Mandatory| Description | 342| -------- | ------------------- | ---- | ------------------------------------------ | 343| tokenID | number | Yes | Application token ID, which is the value of **accessTokenId** in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 344| permissionName | Permissions | Yes | Permission to check. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 345 346**Return value** 347 348| Type | Description | 349| :------------ | :---------------------------------- | 350| [GrantStatus](#grantstatus) | Permission grant state.| 351 352**Error codes** 353 354For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 355 356| ID| Error Message| 357| -------- | -------- | 358| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 359| 12100001 | Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters. | 360 361**Example** 362 363```ts 364import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit'; 365 366let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 367let 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. 368let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'; 369let data: abilityAccessCtrl.GrantStatus = atManager.checkAccessTokenSync(tokenID, permissionName); 370console.log(`data->${JSON.stringify(data)}`); 371``` 372 373### GrantStatus 374 375Enumerates the permission grant states. 376 377**Atomic service API**: This API can be used in atomic services since API version 11. 378 379**System capability**: SystemCapability.Security.AccessToken 380 381| Name | Value| Description | 382| ------------------ | ----- | ----------- | 383| PERMISSION_DENIED | -1 | The permission is not granted.| 384| PERMISSION_GRANTED | 0 | The permission is granted.| 385 386### requestPermissionOnSetting<sup>12+</sup> 387 388requestPermissionOnSetting(context: Context, permissionList: Array<Permissions>): Promise<Array<GrantStatus>> 389 390Requests permissions in a **Settings** dialog box. This API displays a permission settings dialog box for a UIAbility/UIExtensionAbility to grant permissions the second time. 391 392Before calling this API, the application must have called [requestPermissionsFromUser](#requestpermissionsfromuser9). If the user grants the permissions required when the authorization dialog box is displayed the first time, calling this API will not display the permission settings dialog box. 393 394> **NOTE** 395> 396> This API supports only UIAbilities/UIExtensionAbilities. 397 398**Atomic service API**: This API can be used in atomic services since API version 12. 399 400**Model restriction**: This API can be used only in the stage model. 401 402**System capability**: SystemCapability.Security.AccessToken 403 404**Parameters** 405 406| Name| Type| Mandatory| Description| 407| -------- | -------- | -------- | -------- | 408| context | [Context](js-apis-inner-application-context.md) | Yes| Context of the UIAbility/UIExtensionAbility that requests the permissions.| 409| permissionList | Array<Permissions> | Yes| Permissions to request. For details about the permissions, see [Application Permission Groups](../../security/AccessToken/app-permission-group-list.md).| 410 411**Return value** 412 413| Type | Description | 414| :------------ | :---------------------------------- | 415| Promise<Array<[GrantStatus](#grantstatus)>> | Promise used to return the permission grant state.| 416 417**Error codes** 418 419For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 420 421| ID| Error Message| 422| -------- | -------- | 423| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 424| 12100001 | Invalid parameter. Possible causes: 1. The context is invalid because it does not belong to the application itself; 2. The permission list contains the permission that is not declared in the module.json file; 3. The permission list is invalid because the permissions in it do not belong to the same permission group. | 425| 12100010 | The request already exists. | 426| 12100011 | All permissions in the permission list have been granted. | 427| 12100012 | The permission list contains the permission that has not been revoked by the user. | 428 429**Example** 430For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 431 432```ts 433import { abilityAccessCtrl, Context, common } from '@kit.AbilityKit'; 434import { BusinessError } from '@kit.BasicServicesKit'; 435 436let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 437let context: Context = getContext(this) as common.UIAbilityContext; 438atManager.requestPermissionOnSetting(context, ['ohos.permission.CAMERA']).then((data: Array<abilityAccessCtrl.GrantStatus>) => { 439 console.info('data:' + JSON.stringify(data)); 440}).catch((err: BusinessError) => { 441 console.error('data:' + JSON.stringify(err)); 442}); 443``` 444 445### requestGlobalSwitch<sup>12+</sup> 446 447requestGlobalSwitch(context: Context, type: SwitchType): Promise<boolean> 448 449Displays a dialog box for setting a global switch. 450 451When the features such as recording and photographing are disabled, the application can call this API to open the dialog box, asking the user to enable the related features. If the global switch is turned on, no dialog box will be displayed. 452 453> **NOTE** 454> 455> This API supports only UIAbilities/UIExtensionAbilities. 456 457**Atomic service API**: This API can be used in atomic services since API version 12. 458 459**Model restriction**: This API can be used only in the stage model. 460 461**System capability**: SystemCapability.Security.AccessToken 462 463**Parameters** 464 465| Name| Type| Mandatory| Description| 466| -------- | -------- | -------- | -------- | 467| context | [Context](js-apis-inner-application-context.md) | Yes| Context of the UIAbility/UIExtensionAbility.| 468| type | [SwitchType](#switchtype12) | Yes| Type of the global switch.| 469 470**Return value** 471 472| Type | Description | 473| :------------ | :---------------------------------- | 474| Promise<boolean> | Promise used to return the global switch status.| 475 476**Error codes** 477 478For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 479 480| ID| Error Message| 481| -------- | -------- | 482| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 483| 12100001 | Invalid parameter. Possible causes: 1. The context is invalid because it does not belong to the application itself; 2. The type of global switch is not support. | 484| 12100010 | The request already exists. | 485| 12100013 | The specific global switch is already open. | 486 487**Example** 488For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 489 490```ts 491import { abilityAccessCtrl, Context, common } from '@kit.AbilityKit'; 492import { BusinessError } from '@kit.BasicServicesKit'; 493 494let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 495let context: Context = getContext(this) as common.UIAbilityContext; 496atManager.requestGlobalSwitch(context, abilityAccessCtrl.SwitchType.CAMERA).then((data: Boolean) => { 497 console.info('data:' + JSON.stringify(data)); 498}).catch((err: BusinessError) => { 499 console.error('data:' + JSON.stringify(err)); 500}); 501``` 502 503### SwitchType<sup>12+</sup> 504 505Enumerates the global switch types. 506 507**Atomic service API**: This API can be used in atomic services since API version 12. 508 509**System capability**: SystemCapability.Security.AccessToken 510 511| Name | Value| Description | 512| ------------------ | ----- | ----------- | 513| CAMERA | 0 | Global switch of the camera.| 514| MICROPHONE | 1 | Global switch of the microphone.| 515| LOCATION | 2 | Global switch of the location service.| 516