Skip to main content

Authorization

Follow this guide to create a new Apple Ads credential that will allow Nexla to authenticate to and exchange data with your Apple Ads (Apple Search Ads) account.
apple_ads_api_auth.png

Apple Ads

Prerequisites​

The Apple Ads Campaign Management API uses OAuth 2.0 with a server-to-server (two-legged) client credentials flow. Each authenticated request is signed with an access token issued by Apple's identity service at https://appleid.apple.com/auth/oauth2/token. To obtain an access token, you must register an API client in your Apple Ads account, generate a private/public key pair, upload the public key to Apple Ads, and use the private key to mint a signed JWT that serves as the OAuth2 client secret.

The credential in Nexla requires the following four values:

  • Client ID — Issued by Apple Ads when you upload your public key.

  • Client Secret (JWT) — A JWT signed with your private key (ES256). This value replaces the static client secret used in traditional OAuth2 flows.

  • Access Token URL — Apple's OAuth2 token endpoint, https://appleid.apple.com/auth/oauth2/token.

  • Organization ID (orgId) — The Apple Ads organization ID, sent on every API call in the X-AP-Context request header.

Complete the steps in the sections below to obtain these values before creating a credential in Nexla.

Set Up an Apple Ads API User​

To use the Campaign Management API on behalf of your organization, an Account Admin must designate or invite a user with API access.

  1. Sign in to your Apple Ads account at ads.apple.com as an Account Admin.

  2. Navigate to Account Settings, and select the User Management tab.

  3. Invite a new user or edit an existing user, and assign one of the following API roles:

    • API Account Manager — Full read/write access to the API across the organization.

    • API Account Read Only — Read-only access to the API.

    • Limited Access API Read & Write — Read/write access scoped to specific campaigns.

    • Limited Access API Read Only — Read-only access scoped to specific campaigns.

  4. Save the user. The invited user receives an email and must accept the invitation before the API role takes effect.

For complete information about Apple Ads user roles, see Campaign Management API in the Apple Ads Help Center.

Generate a Private/Public Key Pair​

Apple Ads OAuth2 uses an asymmetric key pair. The private key stays on your systems and is used to sign the client secret JWT. The public key is uploaded to Apple Ads.

  1. On a machine with OpenSSL installed, generate an Elliptic Curve (P-256) private key in PEM format. For example:

    openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem

  2. Derive the corresponding public key from the private key:

    openssl ec -in private-key.pem -pubout -out public-key.pem

  3. Store the private key (private-key.pem) in a secure secret manager. It will be used to sign the client secret JWT and cannot be regenerated from the public key.

    Apple recommends ECC with the P-256 curve (algorithm ES256). Other curves or RSA keys are not accepted by the Apple Ads OAuth2 token endpoint.

Upload the Public Key and Create an API Client​

After the API user is set up and the key pair is generated, the API user uploads the public key to Apple Ads to receive a Client ID, Team ID, and Key ID.

  1. Sign in to your Apple Ads account as the API user designated in the previous section.

  2. Navigate to Account Settings, and select the API tab.

  3. On the API screen, click Create to register a new API client.

  4. Paste the contents of public-key.pem (generated in the previous section) into the Public Key field.

  5. Submit the form. Apple Ads displays a code block containing the following values, which are required to mint the client secret JWT:

    • Client ID — The clientId value (used as the JWT sub claim and as the OAuth2 client ID).

    • Team ID — The teamId value (used as the JWT iss claim).

    • Key ID — The keyId value (used in the JWT header).

  6. Copy and store all three values. The Client ID is also entered directly into the Nexla credential.

Generate the Client Secret JWT​

The client secret used for the OAuth2 token request is a JWT signed with your private key. The JWT must be regenerated periodically because Apple enforces a maximum lifetime of 180 days.

  1. Construct the JWT with the following header and payload:

    • Header

      • alg: ES256

      • kid: Your Key ID (from the previous section)

    • Payload

      • sub: Your Client ID

      • aud: https://appleid.apple.com

      • iss: Your Team ID

      • iat: Current Unix timestamp (issued-at time)

      • exp: Unix timestamp at which the JWT should expire (must be no more than 180 days after iat)

  2. Sign the JWT using the private key (private-key.pem) and the ES256 algorithm. The resulting compact JWT string is the value that Nexla uses as the Client Secret (JWT).

    Apple provides reference Python code for generating the client secret JWT. For details, see Implementing OAuth for the Apple Ads API.

  3. Store the JWT in a secure secret manager, and schedule a rotation before the exp value is reached. Once the JWT expires, Apple's token endpoint returns invalid_client, and Nexla will be unable to obtain a new access token until a fresh JWT is supplied.

Locate Your Organization ID​

The Apple Ads orgId identifies the organization for which API calls are scoped. Every Campaign Management API request must include the header X-AP-Context: orgId=<your-orgId>,…. Nexla constructs this header automatically using the value supplied on the credential.

  1. Sign in to your Apple Ads account.

  2. Click your account avatar in the top-right corner of the screen. The organization name and orgId are listed in the account switcher.

  3. Copy the orgId value for use when configuring the Nexla credential.

Important

The Client Secret (JWT) and private key grant access to your Apple Ads account. Store them in a secure secret manager, never commit them to source control, and rotate them immediately if you suspect they have been exposed.

For complete information about authenticating to the Apple Ads API, see Implementing OAuth for the Apple Ads API and Calling the Apple Ads API.

Create an Apple Ads Credential​

  • To create a new Apple Ads credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used to provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

Apple Ads OAuth2 (2-Legged) Settings​

Apple Ads uses a server-to-server OAuth2 client credentials flow. Nexla exchanges your Client ID and signed client secret JWT for an access token, and includes the organization ID on every API call.

  1. Enter the Client ID issued by Apple Ads when the public key was uploaded in the Client ID field. This value identifies your registered API client.

  2. Enter the signed JWT produced in the Generate the Client Secret JWT section in the Client Secret (JWT) field. This value is treated as a secret and must be regenerated before its exp claim is reached.

    The JWT must be signed with the ES256 algorithm using the private key that corresponds to the public key uploaded to Apple Ads. Apple enforces a maximum lifetime of 180 days on the JWT.

  3. Enter the Apple identity token endpoint in the Access Token URL field. The default value https://appleid.apple.com/auth/oauth2/token is correct for production Apple Ads accounts and should be left unchanged unless directed otherwise by Apple.

  4. Enter your Apple Ads organization ID in the Organization ID (orgId) field. Nexla automatically supplies this value in the X-AP-Context header on every API call.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential.

  2. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.