The abilityAccessCtrl module provides APIs for application permission management, including authentication and authorization.
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.
createAtManager(): AtManager
Creates an AtManager instance for application access control.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Security.AccessToken
Return value
| Type | Description |
|---|---|
| AtManager | AtManager instance created. |
Example
let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
checkAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus>
Checks whether a permission is granted to an application. This API uses a promise to return the result.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Security.AccessToken
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| tokenID | number | Yes | Application token ID, which is the value of accessTokenId in ApplicationInfo. |
| permissionName | Permissions | Yes | Permission to check. For details about the permissions, see Permissions for All Applications. |
Return value
| Type | Description |
|---|---|
| Promise<GrantStatus> | Promise used to return the permission grant state. |
Error codes
For details about the error codes, see Access Control Error Codes.
| ID | Error Message |
|---|---|
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 12100001 | Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters. |
Example
import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a third-party application.
atManager.checkAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => {
console.log(`checkAccessToken success, data->${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
console.error(`checkAccessToken fail, err->${JSON.stringify(err)}`);
}); verifyAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus
Verifies whether a permission is granted to an application. This API returns the result synchronously.
System capability: SystemCapability.Security.AccessToken
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| tokenID | number | Yes | Application token ID, which is the value of accessTokenId in ApplicationInfo. |
| permissionName | Permissions | Yes | Permission to verify. For details about the permissions, see Permissions for All Applications. |
Return value
| Type | Description |
|---|---|
| GrantStatus | Permission grant state. |
Error codes
For details about the error codes, see Access Control Error Codes.
| ID | Error Message |
|---|---|
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 12100001 | Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters. |
Example
import { abilityAccessCtrl } from '@kit.AbilityKit';
let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a third-party application.
try {
let data: abilityAccessCtrl.GrantStatus = atManager.verifyAccessTokenSync(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS');
console.log(`data->${JSON.stringify(data)}`);
} catch(err) {
console.error(`catch err->${JSON.stringify(err)}`);
} verifyAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus>
Verifies whether a permission is granted to an application. This API uses a promise to return the result.
System capability: SystemCapability.Security.AccessToken
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| tokenID | number | Yes | Application token ID, which is the value of accessTokenId in ApplicationInfo. |
| permissionName | Permissions | Yes | Permission to verify. For details about the permissions, see Permissions for All Applications. |
Return value
| Type | Description |
|---|---|
| Promise<GrantStatus> | Promise used to return the permission grant state. |
Example
import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a third-party application.
let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS';
atManager.verifyAccessToken(tokenID, permissionName).then((data: abilityAccessCtrl.GrantStatus) => {
console.log(`promise: data->${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
console.error(`verifyAccessToken fail, err->${JSON.stringify(err)}`);
}); requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>, requestCallback: AsyncCallback<PermissionRequestResult>): void
Requests user authorization in a dialog box opened by aUIAbility/UIExtensionAbility. This API uses an asynchronous callback to return the result.
If 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 to display the permission settings dialog box for the user to grant the permission.
OnlyUIAbility/UIExtensionAbility is supported.
Atomic service API: This API can be used in atomic services since API version 12.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Security.AccessToken
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| context | Context | Yes | Context of theUIAbility/UIExtensionAbility that requests the permission. |
| permissionList | Array<Permissions> | Yes | Permissions to request. For details about the permissions, see Permissions for All Applications. |
| requestCallback | AsyncCallback<PermissionRequestResult> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Access Control Error Codes.
| ID | Error Message |
|---|---|
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 12100001 | Invalid parameter. The context is invalid when it does not belong to the application itself. |
Example
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
For details about the process and example of applying for user authorization, see Requesting User Authorization.
import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let context: Context = getContext(this) as common.UIAbilityContext;
atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA'], (err: BusinessError, data: PermissionRequestResult) => {
if (err) {
console.error(`requestPermissionsFromUser fail, err->${JSON.stringify(err)}`);
} else {
console.info('data:' + JSON.stringify(data));
console.info('data permissions:' + data.permissions);
console.info('data authResults:' + data.authResults);
console.info('data dialogShownResults:' + data.dialogShownResults);
}
}); requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>): Promise<PermissionRequestResult>
Requests user authorization in a dialog box opened by aUIAbility/UIExtensionAbility. This API uses a promise to return the result.
If 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 to display the permission settings dialog box for the user to grant the permission.
OnlyUIAbility/UIExtensionAbility is supported.
Atomic service API: This API can be used in atomic services since API version 11.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Security.AccessToken
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| context | Context | Yes | Context of theUIAbility/UIExtensionAbility that requests the permission. |
| permissionList | Array<Permissions> | Yes | Permissions to request. For details about the permissions, see Permissions for All Applications. |
Return value
| Type | Description |
|---|---|
| Promise<PermissionRequestResult> | Promise used to return the result. |
Error codes
For details about the error codes, see Access Control Error Codes.
| ID | Error Message |
|---|---|
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 12100001 | Invalid parameter. The context is invalid when it does not belong to the application itself. |
Example
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
For details about the process and example of applying for user authorization, see Requesting User Authorization.
import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let context: Context = getContext(this) as common.UIAbilityContext;
atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA']).then((data: PermissionRequestResult) => {
console.info('data:' + JSON.stringify(data));
console.info('data permissions:' + data.permissions);
console.info('data authResults:' + data.authResults);
console.info('data dialogShownResults:' + data.dialogShownResults);
}).catch((err: BusinessError) => {
console.error('data:' + JSON.stringify(err));
}); verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus>
Verifies whether a permission is granted to an application. This API uses a promise to return the result.
System capability: SystemCapability.Security.AccessToken
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| tokenID | number | Yes | Application token ID, which is the value of accessTokenId in ApplicationInfo. |
| permissionName | string | Yes | Permission to verify. For details about the permissions, see Permissions for All Applications. |
Return value
| Type | Description |
|---|---|
| Promise<GrantStatus> | Promise used to return the permission grant state. |
Example
import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a third-party application.
atManager.verifyAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => {
console.log(`promise: data->${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
console.error(`verifyAccessToken fail, err->${JSON.stringify(err)}`);
}); checkAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus
Checks whether a permission is granted to an application. This API returns the result synchronously.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Security.AccessToken
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| tokenID | number | Yes | Application token ID, which is the value of accessTokenId in ApplicationInfo. |
| permissionName | Permissions | Yes | Permission to check. For details about the permissions, see Permissions for All Applications. |
Return value
| Type | Description |
|---|---|
| GrantStatus | Permission grant state. |
Error codes
For details about the error codes, see Access Control Error Codes.
| ID | Error Message |
|---|---|
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 12100001 | Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters. |
Example
import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit';
let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a third-party application.
let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS';
let data: abilityAccessCtrl.GrantStatus = atManager.checkAccessTokenSync(tokenID, permissionName);
console.log(`data->${JSON.stringify(data)}`); requestPermissionOnSetting(context: Context, permissionList: Array<Permissions>): Promise<Array<GrantStatus>>
Requests permissions in a Settings dialog box. This API displays a permission settings dialog box for a UIAbility/UIExtensionAbility to grant permissions the second time.
Before calling this API, the application must have called requestPermissionsFromUser. 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.
This API supports only UIAbilities/UIExtensionAbilities.
Atomic service API: This API can be used in atomic services since API version 12.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Security.AccessToken
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| context | Context | Yes | Context of the UIAbility/UIExtensionAbility that requests the permissions. |
| permissionList | Array<Permissions> | Yes | Permissions to request. For details about the permissions, see Application Permission Groups. |
Return value
| Type | Description |
|---|---|
| Promise<Array<GrantStatus>> | Promise used to return the permission grant state. |
Error codes
For details about the error codes, see Access Control Error Codes.
| ID | Error Message |
|---|---|
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 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. |
| 12100010 | The request already exists. |
| 12100011 | All permissions in the permission list have been granted. |
| 12100012 | The permission list contains the permission that has not been revoked by the user. |
Example
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
import { abilityAccessCtrl, Context, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let context: Context = getContext(this) as common.UIAbilityContext;
atManager.requestPermissionOnSetting(context, ['ohos.permission.CAMERA']).then((data: Array<abilityAccessCtrl.GrantStatus>) => {
console.info('data:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error('data:' + JSON.stringify(err));
}); requestGlobalSwitch(context: Context, type: SwitchType): Promise<boolean>
Displays a dialog box for setting a global switch.
When 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.
This API supports only UIAbilities/UIExtensionAbilities.
Atomic service API: This API can be used in atomic services since API version 12.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Security.AccessToken
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| context | Context | Yes | Context of the UIAbility/UIExtensionAbility. |
| type | SwitchType | Yes | Type of the global switch. |
Return value
| Type | Description |
|---|---|
| Promise<boolean> | Promise used to return the global switch status. |
Error codes
For details about the error codes, see Access Control Error Codes.
| ID | Error Message |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 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. |
| 12100010 | The request already exists. |
| 12100013 | The specific global switch is already open. |
Example
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
import { abilityAccessCtrl, Context, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let context: Context = getContext(this) as common.UIAbilityContext;
atManager.requestGlobalSwitch(context, abilityAccessCtrl.SwitchType.CAMERA).then((data: Boolean) => {
console.info('data:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error('data:' + JSON.stringify(err));
}); Enumerates the permission grant states.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Security.AccessToken
| Name | Value | Description |
|---|---|---|
| PERMISSION_DENIED | -1 | The permission is not granted. |
| PERMISSION_GRANTED | 0 | The permission is granted. |
Enumerates the global switch types.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.Security.AccessToken
| Name | Value | Description |
|---|---|---|
| CAMERA | 0 | Global switch of the camera. |
| MICROPHONE | 1 | Global switch of the microphone. |
| LOCATION | 2 | Global switch of the location service. |