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