Authorization

Request and manage HealthKit authorization permissions

HealthKit requires explicit user authorization before your app can read or write health data. The authorization API provides functions to request permissions and check authorization status.

Request authorization

requestAuthorization

Request authorization to read and/or write specific data types.

function requestAuthorization(
  toRequest: AuthDataTypes
): Promise<boolean>

toRequest · AuthDataTypes · required

Authorization request specifying data types to read and/or write

Show AuthDataTypes properties

toShare · SampleTypeIdentifierWriteable[]

Array of data types your app wants to write to HealthKit

toRead · ObjectTypeIdentifier[]

Array of data types your app wants to read from HealthKit

Returns: Promise<boolean> - Resolves to true if authorization was successful

Example: Request read permissions

import { requestAuthorization } from '@kingstinct/react-native-healthkit';

const success = await requestAuthorization({
  toRead: [
    'HKQuantityTypeIdentifierStepCount',
    'HKQuantityTypeIdentifierHeartRate',
    'HKCategoryTypeIdentifierSleepAnalysis',
  ],
});

if (success) {
  console.log('Authorization granted');
}

Example: Request read and write permissions

await requestAuthorization({
  toRead: [
    'HKQuantityTypeIdentifierBloodGlucose',
    'HKQuantityTypeIdentifierInsulinDelivery',
  ],
  toShare: [
    'HKQuantityTypeIdentifierInsulinDelivery',
    'HKQuantityTypeIdentifierBloodGlucose',
  ],
});

Always request authorization before attempting to read or write data. Failing to do so will cause your app to crash.

Check authorization status

authorizationStatusFor

Get the current authorization status for a specific data type.

function authorizationStatusFor(
  type: ObjectTypeIdentifier
): AuthorizationStatus

type · ObjectTypeIdentifier · required

The HealthKit data type to check authorization for

Returns: AuthorizationStatus - One of:

• AuthorizationStatus.notDetermined - User hasn’t been asked yet
• AuthorizationStatus.sharingDenied - User denied access
• AuthorizationStatus.sharingAuthorized - User granted access

import { authorizationStatusFor, AuthorizationStatus } from '@kingstinct/react-native-healthkit';

const status = authorizationStatusFor('HKQuantityTypeIdentifierStepCount');

if (status === AuthorizationStatus.notDetermined) {
  // Request authorization
  await requestAuthorization({
    toRead: ['HKQuantityTypeIdentifierStepCount'],
  });
}

For privacy reasons, you cannot distinguish between the user denying permission and no data being available. Read authorization status will always return notDetermined or sharingAuthorized.

getRequestStatusForAuthorization

Check if authorization has already been requested for specific data types.

function getRequestStatusForAuthorization(
  toCheck: AuthDataTypes
): Promise<AuthorizationRequestStatus>

Returns: Promise<AuthorizationRequestStatus> - One of:

• AuthorizationRequestStatus.unnecessary - Already authorized
• AuthorizationRequestStatus.shouldRequest - Should request authorization
• AuthorizationRequestStatus.unknown - Status unknown

import { getRequestStatusForAuthorization } from '@kingstinct/react-native-healthkit';

const status = await getRequestStatusForAuthorization({
  toRead: ['HKQuantityTypeIdentifierStepCount'],
  toShare: ['HKQuantityTypeIdentifierBodyMass'],
});

if (status === 'shouldRequest') {
  await requestAuthorization({
    toRead: ['HKQuantityTypeIdentifierStepCount'],
    toShare: ['HKQuantityTypeIdentifierBodyMass'],
  });
}

Per-object authorization

requestPerObjectReadAuthorization

For sensitive data types, request authorization on a per-object basis.

function requestPerObjectReadAuthorization(
  typeIdentifier: PerObjectTypeIdentifier
): Promise<void>

typeIdentifier · PerObjectTypeIdentifier · required

The sensitive data type requiring per-object authorization

Available for:

• Clinical records
• Sensitive medical data

import { requestPerObjectReadAuthorization } from '@kingstinct/react-native-healthkit';

await requestPerObjectReadAuthorization(
  'HKClinicalTypeIdentifierLabResults'
);

Per-object authorization is required for clinical records and other sensitive data types. The user will be prompted to approve access to individual records.

React Hook

For declarative authorization management, use the useHealthkitAuthorization hook:

import { useHealthkitAuthorization } from '@kingstinct/react-native-healthkit';

const [authorizationStatus, requestAuth] = useHealthkitAuthorization([
  'HKQuantityTypeIdentifierStepCount',
  'HKQuantityTypeIdentifierHeartRate',
]);

See useHealthkitAuthorization for details.

Related APIs

• useHealthkitAuthorization hook
• Check availability
• Authorization guide