Bundle IDs

Manage bundle IDs and app capabilities

Create, update, and manage bundle identifiers and their associated capabilities.

Overview

Bundle IDs uniquely identify your apps on Apple platforms. The bundle-ids command manages bundle identifiers and their capabilities in App Store Connect.

List Bundle IDs

List all bundle IDs in your account:

# List all bundle IDs
asc bundle-ids list

# Limit results per page
asc bundle-ids list --limit 50

# Fetch all pages automatically
asc bundle-ids list --paginate

# Output as table
asc bundle-ids list --output table

Pagination Options

--limit - Results per page (1-200)
--next - Fetch next page using a links.next URL
--paginate - Automatically fetch all pages

Get Bundle ID Details

Retrieve a specific bundle ID by resource ID:

asc bundle-ids view --id "BUNDLE_ID"

Note: The --id parameter expects the App Store Connect resource ID, not the bundle identifier string (e.g., “com.example.app”). Use list to find the resource ID.

Create Bundle ID

asc bundle-ids create --identifier "com.example.app" \
  --name "Example App" \
  --platform IOS

Required Parameters

--identifier - Bundle ID string (e.g., com.example.app)
--name - Display name for the bundle ID

Optional Parameters

--platform - Platform: IOS (default), MAC_OS, UNIVERSAL

Bundle ID Format

Bundle IDs must follow these rules:

Use reverse DNS notation: com.company.app
Contain only alphanumeric characters (A-Z, a-z, 0-9), hyphens (-), and periods (.)
Cannot start or end with a period
Cannot contain consecutive periods

Valid examples:

com.example.myapp
com.example.my-app
com.example.myapp.watchkit

Invalid examples:

.com.example.app (starts with period)
com..example.app (consecutive periods)
com.example.app! (special characters)

Wildcard Bundle IDs

Create wildcard bundle IDs for app groups:

asc bundle-ids create --identifier "com.example.*" \
  --name "Example App Family" \
  --platform IOS

Wildcard limitations:

Can only use * as the last component
Cannot use certain capabilities (Push Notifications, In-App Purchase, etc.)
Useful for app extensions and development

Update Bundle ID

Update a bundle ID’s display name:

asc bundle-ids update --id "BUNDLE_ID" --name "New Name"

Note: You cannot change the bundle identifier string itself. Only the display name can be updated.

Delete Bundle ID

Delete a bundle identifier:

asc bundle-ids delete --id "BUNDLE_ID" --confirm

Warning: Deleting a bundle ID:

Cannot be undone
Invalidates all associated provisioning profiles
Removes all capability configurations
Should only be done if the bundle ID is no longer in use

Bundle ID Relationships

Get Associated App

Find the app using this bundle ID:

asc bundle-ids app view --id "BUNDLE_ID"

List Associated Profiles

List all provisioning profiles for a bundle ID:

asc bundle-ids profiles list --id "BUNDLE_ID"

Capabilities Management

Manage app capabilities for a bundle ID.

List Capabilities

List all capabilities for a bundle ID:

asc bundle-ids capabilities list --bundle "BUNDLE_ID"

# Fetch all pages
asc bundle-ids capabilities list --bundle "BUNDLE_ID" --paginate

Add Capability

Enable a capability for a bundle ID:

# Simple capability (no settings)
asc bundle-ids capabilities add --bundle "BUNDLE_ID" \
  --capability PUSH_NOTIFICATIONS

# Capability with settings (iCloud)
asc bundle-ids capabilities add --bundle "BUNDLE_ID" \
  --capability ICLOUD \
  --settings '[{"key":"ICLOUD_VERSION","options":[{"key":"XCODE_13","enabled":true}]}]'

Common Capability Types

No settings required:

PUSH_NOTIFICATIONS - Push notifications
IN_APP_PURCHASE - In-App Purchase
GAME_CENTER - Game Center
WALLET - Wallet (Apple Pay)
SIRIKIT - SiriKit
PERSONAL_VPN - Personal VPN
NETWORK_EXTENSIONS - Network Extensions
HOTSPOT - Hotspot Configuration
MULTIPATH - Multipath networking
NFC_TAG_READING - NFC tag reading

Settings required:

ICLOUD - iCloud (CloudKit/Documents)
APP_GROUPS - App Groups
ASSOCIATED_DOMAINS - Associated Domains
DATA_PROTECTION - Data Protection
HEALTHKIT - HealthKit
HOMEKIT - HomeKit
WIRELESS_ACCESSORY_CONFIGURATION - Wireless Accessory

iCloud Capability

# Enable iCloud with CloudKit
asc bundle-ids capabilities add --bundle "BUNDLE_ID" \
  --capability ICLOUD \
  --settings '[{"key":"ICLOUD_VERSION","options":[{"key":"XCODE_13","enabled":true}]}]'

# Enable legacy iCloud (documents)
asc bundle-ids capabilities add --bundle "BUNDLE_ID" \
  --capability ICLOUD \
  --settings '[{"key":"ICLOUD_VERSION","options":[{"key":"XCODE_9","enabled":true}]}]'

App Groups Capability

asc bundle-ids capabilities add --bundle "BUNDLE_ID" \
  --capability APP_GROUPS \
  --settings '[{"key":"APP_GROUP_IDS","options":[{"key":"group.com.example.shared","enabled":true}]}]'

Update Capability

Modify capability settings:

asc bundle-ids capabilities update --id "CAPABILITY_ID" \
  --settings '[{"key":"ICLOUD_VERSION","options":[{"key":"XCODE_13","enabled":true}]}]'

# Change capability type
asc bundle-ids capabilities update --id "CAPABILITY_ID" \
  --capability PUSH_NOTIFICATIONS

Remove Capability

Disable a capability:

asc bundle-ids capabilities remove --id "CAPABILITY_ID" --confirm

Note: Removing capabilities may cause provisioning profiles to become invalid. Regenerate profiles after capability changes.

Complete Example Workflows

Create App with Capabilities

# 1. Create bundle ID
asc bundle-ids create --identifier "com.example.myapp" \
  --name "My App" \
  --platform IOS

# Note BUNDLE_ID from response

# 2. Add Push Notifications
asc bundle-ids capabilities add --bundle "BUNDLE_ID" \
  --capability PUSH_NOTIFICATIONS

# 3. Add In-App Purchase
asc bundle-ids capabilities add --bundle "BUNDLE_ID" \
  --capability IN_APP_PURCHASE

# 4. Add iCloud
asc bundle-ids capabilities add --bundle "BUNDLE_ID" \
  --capability ICLOUD \
  --settings '[{"key":"ICLOUD_VERSION","options":[{"key":"XCODE_13","enabled":true}]}]'

# 5. Verify capabilities
asc bundle-ids capabilities list --bundle "BUNDLE_ID" --output table

App Extensions

Create bundle IDs for app extensions:

# Main app
asc bundle-ids create --identifier "com.example.app" \
  --name "Example App" \
  --platform IOS

# Widget extension
asc bundle-ids create --identifier "com.example.app.widget" \
  --name "Example Widget" \
  --platform IOS

# Share extension
asc bundle-ids create --identifier "com.example.app.share" \
  --name "Example Share Extension" \
  --platform IOS

# Watch app
asc bundle-ids create --identifier "com.example.app.watchkitapp" \
  --name "Example Watch App" \
  --platform IOS

App Groups Setup

Enable app group sharing between main app and extensions:

# 1. Get bundle IDs
asc bundle-ids list --output json | grep "com.example.app"
# Note resource IDs for main app and extensions

# 2. Add App Groups to main app
asc bundle-ids capabilities add --bundle "MAIN_BUNDLE_ID" \
  --capability APP_GROUPS \
  --settings '[{"key":"APP_GROUP_IDS","options":[{"key":"group.com.example.shared","enabled":true}]}]'

# 3. Add App Groups to widget
asc bundle-ids capabilities add --bundle "WIDGET_BUNDLE_ID" \
  --capability APP_GROUPS \
  --settings '[{"key":"APP_GROUP_IDS","options":[{"key":"group.com.example.shared","enabled":true}]}]'

# 4. Add App Groups to share extension
asc bundle-ids capabilities add --bundle "SHARE_BUNDLE_ID" \
  --capability APP_GROUPS \
  --settings '[{"key":"APP_GROUP_IDS","options":[{"key":"group.com.example.shared","enabled":true}]}]'

Associated Domains (Universal Links)

asc bundle-ids capabilities add --bundle "BUNDLE_ID" \
  --capability ASSOCIATED_DOMAINS \
  --settings '[{"key":"ASSOCIATED_DOMAIN_IDS","options":[{"key":"applinks:example.com","enabled":true},{"key":"applinks:www.example.com","enabled":true}]}]'

HealthKit and HomeKit

# HealthKit
asc bundle-ids capabilities add --bundle "BUNDLE_ID" \
  --capability HEALTHKIT

# HomeKit
asc bundle-ids capabilities add --bundle "BUNDLE_ID" \
  --capability HOMEKIT

Platform-Specific Considerations

iOS / tvOS

Most capabilities available. Use --platform IOS (default).

macOS

Some capabilities differ for macOS:

asc bundle-ids create --identifier "com.example.macapp" \
  --name "Example Mac App" \
  --platform MAC_OS

macOS-specific capabilities:

SANDBOX - App Sandbox
SYSTEM_EXTENSION_INSTALL - System Extensions
USER_MANAGEMENT - User Management

Universal (Mac Catalyst)

For Mac Catalyst apps that run on both iOS and macOS:

asc bundle-ids create --identifier "com.example.universal" \
  --name "Example Universal App" \
  --platform UNIVERSAL

Troubleshooting

Bundle ID Already Exists

Error: A bundle ID with identifier 'com.example.app' already exists

Solution:

# List to find existing bundle ID
asc bundle-ids list --output json | grep "com.example.app"

# Use the existing bundle ID or choose a different identifier

Invalid Bundle Identifier Format

Error: Bundle identifier is invalid

Ensure identifier:

Uses reverse DNS notation
Contains only alphanumeric, hyphens, periods
Doesn’t start/end with periods
No consecutive periods

Capability Settings Invalid

JSON settings must be properly formatted:

# Correct format
asc bundle-ids capabilities add --bundle "BUNDLE_ID" \
  --capability ICLOUD \
  --settings '[{"key":"ICLOUD_VERSION","options":[{"key":"XCODE_13","enabled":true}]}]'

Validate JSON:

echo '[{"key":"ICLOUD_VERSION","options":[{"key":"XCODE_13","enabled":true}]}]' | jq .

Provisioning Profiles Invalid After Capability Change

After adding or removing capabilities, regenerate profiles:

# List affected profiles
asc bundle-ids profiles list --id "BUNDLE_ID"

# Delete old profiles
asc profiles delete --id "PROFILE_ID" --confirm

# Create new profiles with updated capabilities
asc profiles create --name "Updated Profile" \
  --profile-type IOS_APP_STORE \
  --bundle "BUNDLE_ID" \
  --certificate "CERT_ID"

Signing - Fetch signing assets
Profiles - Manage provisioning profiles
Certificates - Manage certificates

​Bundle IDs

​Overview

​List Bundle IDs

​Pagination Options

​Get Bundle ID Details

​Create Bundle ID

​Required Parameters

​Optional Parameters

​Bundle ID Format

​Wildcard Bundle IDs

​Update Bundle ID

​Delete Bundle ID

​Bundle ID Relationships

​Get Associated App

​List Associated Profiles

​Capabilities Management

​List Capabilities

​Add Capability

​Common Capability Types

​iCloud Capability

​App Groups Capability

​Update Capability

​Remove Capability

​Complete Example Workflows

​Create App with Capabilities

​App Extensions

​App Groups Setup

​Associated Domains (Universal Links)

​HealthKit and HomeKit

​Platform-Specific Considerations

​iOS / tvOS

​macOS

​Universal (Mac Catalyst)

​Troubleshooting

​Bundle ID Already Exists

​Invalid Bundle Identifier Format

​Capability Settings Invalid

​Provisioning Profiles Invalid After Capability Change

​Related Commands