Authorization Code Flow

Description

The Authorization Code Flow is an OAuth 2.0 grant type that enables a partner platform to obtain access to an Apple Business account on behalf of a user. The user authenticates and grants consent directly with Apple Business, which returns a short-lived authorization code to the partner's registered redirect URI. The partner then exchanges this code server-side for an access token.

Process Flow

Authorization Request Parameters

Name	Input
client_id
code_challenge
response_type
redirect_uri
state

Response Type

MUST be code.

State

MUST be a value that contains a cryptographically random, unpredictable component to prevent cross-site request forgery (CSRF) attacks. This parameter can also be used to encode application-specific context (e.g., a URL to redirect the user to after the flow is complete). Upon receiving the authorization response, the partner's platform MUST validate the state value, including its anti-CSRF component.

Authorization Request Structure

https://business.apple.com/oauth2/v1/authorize?client_id={clientId}&
code_challenge={codeChallenge}&response_type={responseType}&
redirect_uri={redirectionEndpoint}&state={state}

Example Authorization Request

https://business.apple.com/oauth2/v1/authorize?client_id=29352915982374239857&
code_challenge=asdhasfasdfh&response_type=code&
redirect_uri=https://www.third-party.com/authorization&state=xyzABC123

1. Using the authorization request, the partner's platform directs the user to Apple Business, along with parameters
2. Apple Business verifies that:

• Authorization request has a corresponding, registered app in Apple Business
• client_id and redirect_uri match the registered app

3. Once verified, Apple Business stores the code_challenge and state values
4. Launch Apple Business UI

• If user is already logged into Apple Business, a list of approved companies they are a member of are displayed. Else, the user is prompted to login

5. User selects one organization
6. Apple Business displays consent form
7. Apple Business prompts user to allow or deny a partner's request to link the respective accounts
8. If request is allowed, the Apple Business user is redirected to a partner-defined redirection endpoint:

• Partner's platform captures the authorization code and the original state value
• Partner's platform navigates the user to a partner-defined UI

note

code has a lifetime of five (5) minutes

Refer to Request Token for details about next steps.

Authorization Response Parameters

Name	Input
code

Example Authorization Response

{url}?code=g0ZGZmNjVmOWI&state=xyzABC123