> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newly.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Apple and manage signing

> Connect your Apple Developer account to a Newly project with your Apple ID or an App Store Connect API key, and fix signing certificate problems.

Before Newly can upload your app to TestFlight, the project needs a connection to your Apple Developer account. You set this up once per project, inside the **Ship to TestFlight** card. To open the card, ask the agent to "publish to TestFlight". The full publishing flow is on [Ship your iOS app to TestFlight](/publish/testflight).

Before you start:

* **You need to be an organization owner or admin.** A member sees "An organization owner or admin must connect Apple and authorize the upload."
* **You need a saved Newly cloud project**, used from a Remote chat. Otherwise the card shows "Publishing requires a saved Newly cloud project."
* **You need an active Apple Developer Program membership.**

<Warning>
  Never paste Apple passwords, verification codes or keys into the chat. Enter them only in the card.
</Warning>

## Option 1: Sign in with your Apple ID

This is the default, and the quickest way to connect.

<Steps>
  <Step title="Sign in to Apple">
    Under "Sign in to App Store Connect", enter your Apple ID email and password, then press **Sign in to Apple**.
  </Step>

  <Step title="Enter the verification code">
    Apple sends a 6-digit code to your trusted Apple devices. Enter it and press **Verify**.
  </Step>

  <Step title="Choose your Apple team">
    Under "Choose your Apple team.", pick the team that owns the app.
  </Step>

  <Step title="Choose the app">
    Pick an existing app from the list, or choose **Create a new app** and enter:

    * an app name of up to 30 characters
    * a bundle ID, such as `com.yourcompany.yourapp`

    If Apple returns more than one developer team, the card asks you to "Choose the developer team that owns this app."
  </Step>

  <Step title="Connect">
    Press **Connect selected app**. The card shows "Preparing Apple publishing…" while Newly sets things up, then shows your bundle ID and the **Build & upload to TestFlight** button.
  </Step>
</Steps>

### What Newly creates in your Apple account

When you connect with your Apple ID, Newly sets up everything a TestFlight upload needs:

* **The app record** in App Store Connect, if you chose **Create a new app**.
* **An App Store Connect API key** named "Newly" followed by your app name. It has the Admin role, so it can access every app in that Apple team. The card tells you this before you connect. If setup stops before it finishes, Newly tries to delete the key.
* **The bundle ID registration**, if the bundle ID isn't registered yet.
* **An App Store provisioning profile** named "Newly app-store" followed by your bundle ID.
* **A distribution certificate.** Newly reuses it for all your organization's apps in the same Apple team, so it doesn't create a new one for every project.

These appear in your Apple account like any other app, key, profile or certificate. Newly doesn't offer a way to download the certificates or keys it created.

## Option 2: Use an App Store Connect API key

Choose this if you'd rather not sign in with your Apple ID, or your team manages its own keys.

1. In the card, press **Use an API key instead**.
2. Fill in **Bundle ID**, **Apple team ID**, **API key ID** and **Issuer ID**. The team ID and key ID are each 10 uppercase letters or digits.
3. Press **Choose private key (.p8)** and pick the key file you downloaded from App Store Connect.
4. Press **Connect App Store Connect**.

With this option:

* **The app must already exist** in App Store Connect with the same bundle ID. Newly doesn't create it for you.
* **The key needs permission to create signing certificates and provisioning profiles.** Newly checks that the key works and can see your app when you connect. It only finds out whether the key can create certificates and profiles when a release runs, so a key without those permissions fails at that point.

<Note>
  On Mac: if choosing the `.p8` file shows "Open the cloud publishing card in your browser to select a key.", open the same chat in the web app at app.newly.app and connect from there. Apple ID sign-in doesn't ask for a file.
</Note>

To switch back, press **Use Apple sign-in**.

## How your Apple details are stored

* Your Apple password and verification code are used only for that sign-in.
* The publishing key and signing details are encrypted and used only for publishing.
* None of it is shown to the agent or copied into your project's code.
* The connection belongs to one project. Another project needs its own connection.

## Change the app, bundle ID or team

Open the **Ship to TestFlight** card for the project and press **Change Apple settings**. Then connect again with either option.

You can't change Apple settings while a release is running. If you try, Newly shows "Wait for the current release before replacing Apple credentials." Wait for the release to finish, then try again.

## Signing certificates

Apple limits how many distribution certificates a team can have. If your team is at the limit, or Apple reports a conflicting certificate, the release fails and the card shows "Too many signing certificates" or "Signing certificate needs attention".

Press **Manage signing certificates**. You have two ways to fix it.

<Tabs>
  <Tab title="Import an existing certificate">
    Use this if you already have a distribution certificate for this team exported as a `.p12` file.

    1. Press **Choose signing identity (.p12)** and pick the file. It must be under 128 KB and contain one private key for an active distribution certificate in the same Apple team.
    2. Enter the file's password, if it has one.
    3. Press **Import signing identity**.
    4. When you see "Signing certificate ready. You can retry publishing.", press **Retry**.

    Newly encrypts the private key. The file password is used only to import it.

    On Mac, if you see "Open cloud publishing in your browser to import a signing identity.", open the same chat in the web app and import from there.
  </Tab>

  <Tab title="Revoke and replace a certificate">
    Use this if your team has a certificate it no longer needs.

    1. Press **Show certificates**, which shows a count, for example **Show certificates (2)**, to list your team's distribution certificates. Each one shows its expiry date and whether your Newly organization saved it.
    2. Press **Review revocation of…** next to the certificate you want to remove.
    3. Read the warning and press **Confirm revoke and replace**.

    Revoking can't be undone. Other apps or build tools outside Newly may use the same certificate, and Newly can't tell. Check with your team first.

    Once the replacement is ready, Newly builds and uploads the saved version to TestFlight automatically.
  </Tab>
</Tabs>

You can't change certificates while any release in your organization is running. Newly shows "Wait for active releases in this organization before changing signing certificates." Wait for it to finish first.

## Connection errors

<AccordionGroup>
  <Accordion title="&#x22;Apple did not return a developer team for signing…&#x22;">
    Your Apple account signed in, but Apple didn't return a team that can sign apps. Check that the account has an active Apple Developer Program membership and access to Certificates, Identifiers & Profiles. Then press **Retry team lookup**.
  </Accordion>

  <Accordion title="&#x22;Apple rejected the email or password.&#x22;">
    Re-enter your current Apple Account email and password, then press **Retry Apple sign-in**.
  </Accordion>

  <Accordion title="&#x22;Sign into your Apple Account in a browser and complete any pending account prompts, then retry here.&#x22;">
    Apple needs you to finish something in your account first. Sign in on Apple's website, finish the prompts, then try again in the card.
  </Accordion>

  <Accordion title="&#x22;Apple could not create the app because that app name is already in use.&#x22;">
    Apple already has an app with that name. Choose another name.
  </Accordion>

  <Accordion title="&#x22;Apple could not register that bundle ID.&#x22;">
    That bundle ID isn’t available to your team. Choose a unique bundle ID owned by your team.
  </Accordion>

  <Accordion title="&#x22;Create this app in App Store Connect first, using the same bundle ID.&#x22;">
    You're using an API key, and App Store Connect has no app with that bundle ID. Create the app in App Store Connect, or use Apple ID sign-in and choose **Create a new app**.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Ship your iOS app to TestFlight" icon="paper-plane" href="/publish/testflight">
    Build and upload your app from the chat.
  </Card>

  <Card title="App name, icon, bundle ID and version" icon="id-card" href="/publish/app-identity">
    How the bundle ID from your Apple connection is used.
  </Card>
</CardGroup>