Permissions mapping

When you connect a device-native source (Apple Health, Health Connect, Samsung Health, Google Fit), the Terra SDK translates Terra's CustomPermissions into the underlying platform's native permissions. This page lists exactly what each Terra permission requests on each platform, so you can predict what the user sees in the native permission prompt and which metrics will be available.

How permissions are requested

You can request permissions in two ways:

• By data-type group — request ACTIVITY, BODY, DAILY, SLEEP, NUTRITION or MENSTRUATION (this is the default — your developer dashboard scopes). Each group requests a broad set of native types.

• By customPermissions — pass a specific set of CustomPermissions values to request a narrower list. When customPermissions is non-empty, it takes precedence and the default group set is ignored.

The tables below are grouped by data domain (Activity, Heart, Vitals, and so on), with the same categories in the same order on every platform — switch tabs to compare a value across platforms. A value shown as a dash (—) requests no data on that platform.

Permission names vary slightly between SDKs (for example, the React Native and Flutter enums use different casing and a subset of values). The mapping below uses the canonical Terra names; check your SDK's enum for the exact spelling.

Apple Health

Each CustomPermissions value maps to one or more HealthKit types. When you don't pass customPermissions, the SDK requests every type associated with the data-type groups in your developer scopes — so the HealthKit prompt can show a long list. Pass customPermissions to request a narrower set.

Activity & workouts

CustomPermissions value	HealthKit type(s) requested
WORKOUT_TYPE	Workouts
ACTIVITY_SUMMARY	Activity summary, Stand time, Exercise time
ACTIVE_DURATIONS	Exercise time
CALORIES	Active energy burned
BASAL_ENERGY_BURNED	Resting (basal) energy burned
STEPS	Steps
FLIGHTS_CLIMBED	Flights climbed
EXERCISE_DISTANCE	Distance (walking/running, cycling, swimming, wheelchair)
SWIMMING_SUMMARY	Swimming stroke count
LOCATION	Workout route
SPEED	Walking speed (iOS 14+), running speed (16+), cycling speed & cadence (17+)
POWER	Running power (iOS 16+), cycling power (17+)
MINDFULNESS	Mindful sessions

Heart & cardiovascular

CustomPermissions value	HealthKit type(s) requested
HEART_RATE	Heart rate
RESTING_HEART_RATE	Resting heart rate
HEART_RATE_VARIABILITY	Heart rate variability (SDNN)
INTERBEAT	Beat-to-beat measurements
ELECTROCARDIOGRAM	Electrocardiograms (iOS 14+)
VO2MAX	VO₂ max
BLOOD_PRESSURE	Blood pressure (systolic & diastolic)

Vitals

CustomPermissions value	HealthKit type(s) requested
RESPIRATORY_RATE	Respiratory rate
OXYGEN_SATURATION	Blood oxygen
BLOOD_GLUCOSE	Blood glucose
BODY_TEMPERATURE	Body temperature (+ wrist temperature on iOS 16+)

Body measurements

CustomPermissions value	HealthKit type(s) requested
HEIGHT	Height
WEIGHT	Body mass
BMI	Body mass index
BODY_FAT	Body fat percentage
LEAN_BODY_MASS	Lean body mass

Sleep

CustomPermissions value	HealthKit type(s) requested
SLEEP_ANALYSIS	Sleep analysis

Nutrition

CustomPermissions value	HealthKit type(s) requested
NUTRITION_CALORIES	Dietary energy consumed
NUTRITION_PROTEIN	Dietary protein
NUTRITION_CARBOHYDRATES	Dietary carbohydrates
NUTRITION_FAT_TOTAL	Dietary total fat
NUTRITION_FIBRE	Dietary fiber
NUTRITION_SUGAR	Dietary sugar
NUTRITION_SODIUM	Dietary sodium
NUTRITION_CHOLESTEROL	Dietary cholesterol
NUTRITION_VITAMIN_C	Dietary vitamin C
NUTRITION_VITAMIN_A	Dietary vitamin A
NUTRITION_WATER	Dietary water

Reproductive health

CustomPermissions value	HealthKit type(s) requested
MENSTRUATION	Menstrual flow

Profile

CustomPermissions value	HealthKit type(s) requested
GENDER	Biological sex
DATE_OF_BIRTH	Date of birth

Symptoms

CustomPermissions value	HealthKit type(s) requested
SYMPTOM_COUGHING	Coughing (iOS 13.6+)
SYMPTOM_FEVER	Fever (iOS 13.6+)
SYMPTOM_SORE_THROAT	Sore throat (iOS 13.6+)

Requesting a data-type group (rather than customPermissions) requests a broad superset of types. For example, the Body group requests heart rate, HRV, VO₂ max, glucose, blood pressure, body temperature, ECG and more — not just body-composition metrics. Use customPermissions when you want the HealthKit prompt to show only specific toggles.

Health Connect

Samsung Health (direct)