1# @ohos.abilityAccessCtrl (Application Access Control) 2 3The **abilityAccessCtrl** module provides APIs for application permission management, including authentication and authorization. 4 5> **NOTE**<br> 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 third-party 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 third-party 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 third-party 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. Alternatively, call [requestPermissionOnSetting](#requestpermissiononsetting12) to display the permission settings dialog box for the user to grant the permission. 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 used 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** 210 211For 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). 212For details about the process and example of applying for user authorization, see [Requesting User Authorization](../../security/AccessToken/request-user-authorization.md). 213 214```ts 215import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit'; 216import { BusinessError } from '@kit.BasicServicesKit'; 217 218let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 219let context: Context = getContext(this) as common.UIAbilityContext; 220atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA'], (err: BusinessError, data: PermissionRequestResult) => { 221 if (err) { 222 console.error(`requestPermissionsFromUser fail, err->${JSON.stringify(err)}`); 223 } else { 224 console.info('data:' + JSON.stringify(data)); 225 console.info('data permissions:' + data.permissions); 226 console.info('data authResults:' + data.authResults); 227 console.info('data dialogShownResults:' + data.dialogShownResults); 228 } 229}); 230``` 231 232### requestPermissionsFromUser<sup>9+</sup> 233 234requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>): Promise<PermissionRequestResult> 235 236Requests user authorization in a dialog box opened by a <!--RP1-->UIAbility<!--RP1End-->. This API uses a promise to return the result. 237 238If 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. Alternatively, call [requestPermissionOnSetting](#requestpermissiononsetting12) to display the permission settings dialog box for the user to grant the permission. 239 240> **NOTE** 241> 242> Only <!--RP1-->UIAbility<!--RP1End--> is supported. 243 244**Atomic service API**: This API can be used in atomic services since API version 11. 245 246**Model restriction**: This API can be used only in the stage model. 247 248**System capability**: SystemCapability.Security.AccessToken 249 250**Parameters** 251 252| Name| Type| Mandatory| Description| 253| -------- | -------- | -------- | -------- | 254| context | [Context](js-apis-inner-application-context.md) | Yes| Context of the <!--RP1-->UIAbility<!--RP1End--> that requests the permission.| 255| permissionList | Array<Permissions> | Yes| Permissions to request. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 256 257**Return value** 258 259| Type| Description| 260| -------- | -------- | 261| Promise<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Promise used to return the result.| 262 263**Error codes** 264 265For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 266 267| ID| Error Message| 268| -------- | -------- | 269| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 270| 12100001 | Invalid parameter. The context is invalid when it does not belong to the application itself. | 271 272**Example** 273 274For 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). 275For details about the process and example of applying for user authorization, see [Requesting User Authorization](../../security/AccessToken/request-user-authorization.md). 276 277```ts 278import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit'; 279import { BusinessError } from '@kit.BasicServicesKit'; 280 281let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 282let context: Context = getContext(this) as common.UIAbilityContext; 283atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA']).then((data: PermissionRequestResult) => { 284 console.info('data:' + JSON.stringify(data)); 285 console.info('data permissions:' + data.permissions); 286 console.info('data authResults:' + data.authResults); 287 console.info('data dialogShownResults:' + data.dialogShownResults); 288}).catch((err: BusinessError) => { 289 console.error('data:' + JSON.stringify(err)); 290}); 291``` 292 293### verifyAccessToken<sup>(deprecated)</sup> 294 295verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> 296 297Verifies whether a permission is granted to an application. This API uses a promise to return the result. 298 299> **NOTE** 300> 301> This API is no longer maintained since API version 9. Use [checkAccessToken](#checkaccesstoken9) instead. 302 303**System capability**: SystemCapability.Security.AccessToken 304 305**Parameters** 306 307| Name | Type | Mandatory| Description | 308| -------- | ------------------- | ---- | ------------------------------------------ | 309| tokenID | number | Yes | Application token ID, which is the value of **accessTokenId** in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 310| permissionName | string | Yes | Permission to verify. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 311 312**Return value** 313 314| Type | Description | 315| :------------ | :---------------------------------- | 316| Promise<[GrantStatus](#grantstatus)> | Promise used to return the permission grant state.| 317 318**Example** 319 320```ts 321import { abilityAccessCtrl } from '@kit.AbilityKit'; 322import { BusinessError } from '@kit.BasicServicesKit'; 323 324let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 325let 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 third-party application. 326atManager.verifyAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => { 327 console.log(`promise: data->${JSON.stringify(data)}`); 328}).catch((err: BusinessError) => { 329 console.error(`verifyAccessToken fail, err->${JSON.stringify(err)}`); 330}); 331``` 332 333### checkAccessTokenSync<sup>10+</sup> 334 335checkAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus 336 337Checks whether a permission is granted to an application. This API returns the result synchronously. 338 339**Atomic service API**: This API can be used in atomic services since API version 11. 340 341**System capability**: SystemCapability.Security.AccessToken 342 343**Parameters** 344 345| Name | Type | Mandatory| Description | 346| -------- | ------------------- | ---- | ------------------------------------------ | 347| tokenID | number | Yes | Application token ID, which is the value of **accessTokenId** in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 348| permissionName | Permissions | Yes | Permission to check. For details about the permissions, see [Permissions for All Applications](../../security/AccessToken/permissions-for-all.md).| 349 350**Return value** 351 352| Type | Description | 353| :------------ | :---------------------------------- | 354| [GrantStatus](#grantstatus) | Permission grant state.| 355 356**Error codes** 357 358For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 359 360| ID| Error Message| 361| -------- | -------- | 362| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 363| 12100001 | Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters. | 364 365**Example** 366 367```ts 368import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit'; 369 370let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 371let 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 third-party application. 372let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'; 373let data: abilityAccessCtrl.GrantStatus = atManager.checkAccessTokenSync(tokenID, permissionName); 374console.log(`data->${JSON.stringify(data)}`); 375``` 376 377### GrantStatus 378 379Enumerates the permission grant states. 380 381**Atomic service API**: This API can be used in atomic services since API version 11. 382 383**System capability**: SystemCapability.Security.AccessToken 384 385| Name | Value| Description | 386| ------------------ | ----- | ----------- | 387| PERMISSION_DENIED | -1 | The permission is not granted.| 388| PERMISSION_GRANTED | 0 | The permission is granted.| 389 390### requestPermissionOnSetting<sup>12+</sup> 391 392requestPermissionOnSetting(context: Context, permissionList: Array<Permissions>): Promise<Array<GrantStatus>> 393 394Requests permissions in a **Settings** dialog box. This API displays a permission settings dialog box for a UIAbility/UIExtensionAbility to grant permissions the second time. 395 396Before 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. 397 398> **NOTE** 399> 400> This API supports only UIAbilities/UIExtensionAbilities. 401 402**Atomic service API**: This API can be used in atomic services since API version 12. 403 404**Model restriction**: This API can be used only in the stage model. 405 406**System capability**: SystemCapability.Security.AccessToken 407 408**Parameters** 409 410| Name| Type| Mandatory| Description| 411| -------- | -------- | -------- | -------- | 412| context | [Context](js-apis-inner-application-context.md) | Yes| Context of the UIAbility/UIExtensionAbility that requests the permissions.| 413| permissionList | Array<Permissions> | Yes| Permissions to request. For details about the permissions, see [Application Permission Groups](../../security/AccessToken/app-permission-group-list.md).| 414 415**Return value** 416 417| Type | Description | 418| :------------ | :---------------------------------- | 419| Promise<Array<[GrantStatus](#grantstatus)>> | Promise used to return the permission grant state.| 420 421**Error codes** 422 423For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 424 425| ID| Error Message| 426| -------- | -------- | 427| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 428| 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. | 429| 12100010 | The request already exists. | 430| 12100011 | All permissions in the permission list have been granted. | 431| 12100012 | The permission list contains the permission that has not been revoked by the user. | 432 433**Example** 434For 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). 435 436```ts 437import { abilityAccessCtrl, Context, common } from '@kit.AbilityKit'; 438import { BusinessError } from '@kit.BasicServicesKit'; 439 440let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 441let context: Context = getContext(this) as common.UIAbilityContext; 442atManager.requestPermissionOnSetting(context, ['ohos.permission.CAMERA']).then((data: Array<abilityAccessCtrl.GrantStatus>) => { 443 console.info('data:' + JSON.stringify(data)); 444}).catch((err: BusinessError) => { 445 console.error('data:' + JSON.stringify(err)); 446}); 447``` 448 449### requestGlobalSwitch<sup>12+</sup> 450 451requestGlobalSwitch(context: Context, type: SwitchType): Promise<boolean> 452 453Displays a dialog box for setting a global switch. 454 455When 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. 456 457> **NOTE** 458> 459> This API supports only UIAbilities/UIExtensionAbilities. 460 461**Atomic service API**: This API can be used in atomic services since API version 12. 462 463**Model restriction**: This API can be used only in the stage model. 464 465**System capability**: SystemCapability.Security.AccessToken 466 467**Parameters** 468 469| Name| Type| Mandatory| Description| 470| -------- | -------- | -------- | -------- | 471| context | [Context](js-apis-inner-application-context.md) | Yes| Context of the UIAbility/UIExtensionAbility.| 472| type | [SwitchType](#switchtype12) | Yes| Type of the global switch.| 473 474**Return value** 475 476| Type | Description | 477| :------------ | :---------------------------------- | 478| Promise<boolean> | Promise used to return the global switch status.| 479 480**Error codes** 481 482For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 483 484| ID| Error Message| 485| -------- | -------- | 486| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 487| 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. | 488| 12100010 | The request already exists. | 489| 12100013 | The specific global switch is already open. | 490 491**Example** 492For 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). 493 494```ts 495import { abilityAccessCtrl, Context, common } from '@kit.AbilityKit'; 496import { BusinessError } from '@kit.BasicServicesKit'; 497 498let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 499let context: Context = getContext(this) as common.UIAbilityContext; 500atManager.requestGlobalSwitch(context, abilityAccessCtrl.SwitchType.CAMERA).then((data: Boolean) => { 501 console.info('data:' + JSON.stringify(data)); 502}).catch((err: BusinessError) => { 503 console.error('data:' + JSON.stringify(err)); 504}); 505``` 506 507### SwitchType<sup>12+</sup> 508 509Enumerates the global switch types. 510 511**Atomic service API**: This API can be used in atomic services since API version 12. 512 513**System capability**: SystemCapability.Security.AccessToken 514 515| Name | Value| Description | 516| ------------------ | ----- | ----------- | 517| CAMERA | 0 | Global switch of the camera.| 518| MICROPHONE | 1 | Global switch of the microphone.| 519| LOCATION | 2 | Global switch of the location service.| 520