Share Access for Business and Location Management

Overview

Organizations can designate partners to manage their brands and locations.

The partner accepting Share Access then sends data to Apple Maps on behalf of the organization. Partners can take advantage of Brand, Showcase, and Insights API for their client organizations. When OAuth Share Access method is used, a partner can also create brands for the organization.

Prerequisites for Share Access

For Production Use

Before a partner can activate Share Access in production (either through OAuth app or Delegation), they must:

1. Be approved for the production environment
2. Successfully send undelegated data to the production environment

Testing During Onboarding

Partners can test Share Access functionality during the onboarding process. Contact Apple Business support to enable Share Access testing during onboarding.

To enable Share Access testing during onboarding, email Apple Business support.

Default Data Management

When partners do not use Share Access authorization, they use their own Apple Business Service Account to pass their client organization's brand and location data. This is also called undelegated data management.

Undelegated data is:

• Evaluated and pushed to production as data from the partner and not the organization or brand they are representing.
• Processed with the lowest priority.

All production data at production launch is undelegated. This continues until a partner's client organization shares access.

Undelegated partners are not authorized to manage Showcases, Showcase Creatives, flexible action links, Brands, or gather Insights.

Development Path for Partners

Partners typically follow this sequence:

1. Develop and test basic API integration while undelegated
2. Optional: Test Share Access functionality in AIE/DQE environments
3. Get approval for the production environment
4. Begin sending undelegated data to production
5. After successfully sending undelegated data, activate Share Access features in production

Testing vs. Production Activation

Testing Phase

Partners can test Share Access functionality during AIE and DQE phases with approval from Apple Business support. Share Access is only activated after successfully sending undelegated data to production

Integration Steps

1. Prepare for Share Access with:
   • Share Access Workflow with Delegation
   • Share Access Workflow with OAuth app
2. Optional: Test Share Access in AIE/DQE (contact Apple Business support for limited capabilities testing)
3. Share Access in Production (full activation after prerequisites)

Production Activation

Apple requires that partners first demonstrate successful undelegated data submission to production before activating Share Access features. This ensures data quality and proper system integration before enabling the enhanced capabilities of Share Access.

Share Access Benefits

Share Access enables the partner to do the following for their client organizations.

• With OAuth app, partners submit location data using their client organization's orgId and access token.

This means that data submitted by a Share Access partner is treated as though it is submitted by the organization itself, and it has the same prioritization in Apple Maps.

• Create and publish showcases for their client organizations.

• Set up brand cover photo and logo and other branding information on behalf of their client organizations.

• Gather insights about their client organizations' locations and showcases.

• Create and publish flexible action links. See How to Submit Flexible Actions Links.

• When Share Access authorization is through the partner OAuth app, the partner can also create and modify brands for their client organizations.

Share Access Types

• OAuth app - Partner sets up a website, invites the organization to initiate Share Access. Organization allows Share Access on the Apple Business portal.

note

Only OAuth app Share Access option allows the partner to get, create, update, or delete brands for their client organizations.

• Delegation - On the Apple Business portal, the organization invites the partner to manage their data. Partner accepts the invitation.

Important: To accept delegation and manage delegated brands, partners must first be approved for the production environment and have started sending undelegated data. Share Access does not allow a partner to create organizations.

Delegation vs OAuth Access Differences

Feature	OAuth app	Delegation
Requires acceptance by Partner	No	Yes
Create access token with...	Organization access token	Service account token
Create and delete brand	Yes	No
Get and update	Yes	Yes
Manage Media, Showcases, and Showcase Creatives	Yes	Yes
Manage locations' flexible action links	Yes	Yes

OAuth app Features

• OAuth 2.0 is a standard protocol.
• From the client organization's perspective:
  • They are invited to the partner's portal.
  • They initiate the connection between the partner portal and Apple Business.
  • They click a link on the partner's portal, such as Link Apple Business Account.
  • On the Apple Business portal, they click Allow.
• From the partner perspective:
  • Partner adds a link on their platform for their client organizations to click, such as Link Apple Business Account.
  • Partner registers their OAuth app with Apple Business. See OAuth app.
  • When submitting data under the OAuth app, the partner uses the client organization's access token received using Request Access Token or Request Refresh Token. See Partner Accesses the Organization Data.

Delegation Features

Delegation maybe used by partners that don't own a platform to implement OAuth app.

• From the client organization's perspective, they select and invite the partner through the partner's own orgId in the Apple Business portal.
• From the partner perspective:
  • Partner guides the client organization step-by-step on how to enable delegation.
  • Partner accepts the organization's invitation.
  • Partner begins using Business API > Delegation API.
  • When sending data, the partner uses their own Service Account orgId and access token. See Business API > References > Request Token (Svc Acct).

Choose a Share Access Type

OAuth app is the recommended Share Access type for partners that want to create, read, update, and delete brands for their client organizations.

Use Delegation when:

• Partners don't have a platform to implement an OAuth app.
• Partners don't expect to have permissions from client organizations to create brands.

Technical Best Practices

Implementing Share Access

1. Maintain a Robust Notification System: Set up internal notifications to alert your team when Share Access invitations are received or when access changes. See the Notification and Feedback and WebHook Messages sections.

2. Implement Proper Error Handling: When working with shared resources, implement comprehensive error handling to manage cases where permissions might have changed.

3. Use Batch Operations Efficiently: When managing multiple locations for a shared brand, use batch operations where available to improve performance.

4. Track Share Access Status: Maintain a record of all Share Access your organization has been granted, including the scope of access and any limitations.

Managing Shared Resources

1. Separate Shared and Non-Shared Operations: Structure your code to clearly distinguish between operations on shared resources and your own resources.

2. Implement Resource Conflict Resolution: Develop strategies for handling cases where multiple partners with Share Access might be updating the same resources.

3. Regular Validation: Periodically validate that your Share Access is still active and that you can still perform the expected operations.

Error Handling for Share Access

When encountering errors while working with shared resources, consider these common scenarios:

1. Access Revoked: If you receive a 403 Forbidden error when accessing previously accessible resources, the organization may have revoked Share Access.

2. Resource Not Found: A 404 Not Found error might indicate that the resource has been deleted by the organization or another partner with Share Access.

3. Validation Errors: Pay special attention to validation errors (400 Bad Request), as they may indicate that another partner with Share Access has modified the resource structure.

4. Rate Limiting: Be aware that API rate limits apply across all shared resources you manage, so implement appropriate throttling mechanisms.

FAQs

Share Access Setup and Management

Can organizations search for prospective third-party partners in Apple Business?

No, but a list of partners supporting Share Access is available in the Apple Business User Guide. See Approved Business API partners.

Is Share Access at the brand entity level or at the location level?

Share Access is at the brand entity level when Delegation is used and it's at the organization level when OAuth app is used.

How will we be notified that an organization has stopped sharing with us?

Organization administrator roles will receive an email. Enhancement of the Notifications API is expected at a future date.

Resource Access and Management

Can we use the portal to manage an organization's shared resources?

Yes. But it is recommended to edit resources via the API for better results.

Is the view of the list of locations we see the same as the organization that shared access with us?

When a brand is shared, you can view all locations regardless of resource state.

Do portal-only organizations receive the same notifications as API users?

Messaging and presentation are different, but data received via the portal is subject to the same validations we apply to data received via the Business API.

Resource Ownership and Management

Who owns the brand and location assets we submit for an organization?

All current and future resources that exist under the ID of the organization that shared access with you are owned by them. When you accept a Share Access invitation, no resources are systematically transferred from your account to theirs. Deciding what to intentionally migrate from one organization to another is up to the respective parties.

What happens to resources we created when Share Access ends?

You are not required by Apple Business to revert or delete any versions of the resources you possess when Share Access ends. Ultimately, the decision is left to the respective parties.

What should we do with existing brand and locations after being granted Share Access?

You should manage the brand and locations under the ID of the organization that shared access with you. You are not required to delete, update, or otherwise change any of the existing resources currently associated with your organization's ID.

You should not, however, continue to manage the respective representations of their data under your organization ID.

Under which organization ID should we manage brands and locations after being granted Share Access?

After being granted Share Access, you maintain their brand and locations under the ID of the organization that shared access with you.

Permissions and Capabilities

Can partners with Share Access add new brands?

With OAuth app, partners can add and delete brands. With Delegation, you cannot add or delete brands, only the organization that shared access can perform these operations. Once the new brand is added, and assuming the resource is PUBLISHED, you can manage the resource.

Can partners with Share Access delete showcases?

If your assigned role permits it, you should be able to use all available operations.

What does "Verified" status mean for locations?

Verified means that a location claim has been approved by the Apple Business operations team.

How do franchises and franchisees handle Share Access for Showcases?

A franchisee cannot share access to a franchise. A franchisee may, independently, run a Showcase. You, as a franchise, may run Showcases on those same locations. However, in a scenario where a scheduled Showcase "overlaps" yours, the franchisee's Showcase takes precedence.