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

# Rotate Git SSH deploy keys with the API

> Use the API to rotate SSH deploy keys without interrupting Git operations.

[All guides](https://docs.omni.co/guides.md)

Progress

%

Category

api

Last updated

July 2026

# Rotate Git SSH deploy keys with the API

While Omni generates SSH deploy keys automatically when you connect a Git repository, you can also supply your own RSA or ED25519 private key via the API.

If you need to rotate keys—for example, to meet a compliance schedule—the API approach allows you to avoid downtime during the rotation. You first authorize the new public key with your Git provider, supply the private key to Omni, and then remove the unneeded public key from Git. This ensures that both keys work during the transition. The new key will take effect on the next Git operation.

## Requirements

To follow the steps in this guide, you'll need:

* An [Omni API key](https://docs.omni.co/api/authentication.md)
* **Connection Admin** permissions on the model
* A Git-connected model using **SSH authentication**
* The shared model's `modelId`, which you can retrieve using the [List models](https://docs.omni.co/api/models/list-models.md) endpoint
* `ssh-keygen` installed locally to generate keypairs

## Supported key types

Omni accepts RSA and ED25519 private keys in PEM format:

* **OpenSSH format** (default from `ssh-keygen`)
* **PKCS#1 format**
* **PKCS#8 format**

Keys can be passphrase-protected or unencrypted. When you supply an encrypted key, Omni uses the passphrase once to decrypt it, then stores the key under its own encryption at rest. The passphrase is not retained.

## 1. Generate a new keypair

Use `ssh-keygen` to generate a new RSA or ED25519 keypair.

> [tab] ED25519
>
> ```bash wrap theme={null}
> ssh-keygen -t ed25519 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
> ```

> [tab] RSA
>
> ```bash wrap theme={null}
> ssh-keygen -t rsa -b 4096 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
> ```

When prompted for a passphrase:

* **To leave the key unencrypted**, press `Enter`.
* **To encrypt the key**, provide a passphrase. This is more secure at rest, but you'll need to supply it to Omni.

This generates two files:

* `omni_deploy_key` — The private key, which you'll supply to Omni
* `omni_deploy_key.pub` — The public key, which you'll authorize with your Git provider

## 2. Authorize the public key with your Git provider

Add the public key (`omni_deploy_key.pub`) to your Git repository as a deploy key with **write access**. This step ensures the new key is authorized before you supply the private key to Omni.

> [tab] GitHub
>
> 1. In the GitHub repository, click the **Settings** tab.
> 2. Click **Deploy keys**, located in the **Security** section of the sidebar.
> 3. Click **Add deploy key**.
> 4. Fill in the fields as follows:
>    * **Title** - Enter a descriptive title to help you identify what the key is used for. For example, *Omni Snowflake Model*
>    * **Key** - Paste the contents of omni\_deploy\_key.pub.
>    * **Allow write access** - Check this box, which will allow Omni to push changes made in Omni to the repository
> 5. Click **Add key**.

> [tab] GitLab
>
> 1. Create a **project deploy key** for the GitLab repository by following [GitLab's documentation](https://docs.gitlab.com/ee/user/project/deploy_keys/#create-a-project-deploy-key).
>    > [!WARNING]
>    >
>    > If the user who created the deploy key looses access to the repository, the deploy key will not work. GitLab recommends using a [service account](https://docs.gitlab.com/user/profile/service_accounts/) when creating a deploy key so that the key will be unaffected if the [user leaves the organization](https://docs.gitlab.com/user/profile/service_accounts/).
> 2. Fill in the deploy key fields as follows:
>    * **Title** - Enter a descriptive title to help you identify what the key is used for. For example, *Omni Snowflake Model*
>    * **Key** - Paste the contents of omni\_deploy\_key.pub.
>    * **Grant write permissions to this key** - Check this box, which will allow Omni to push changes made in Omni to the repository
> 3. Click **Add key**.

> [tab] Azure DevOps
>
> 1. Browse to the Azure DevOps web portal (ex: `https://dev.azure.com/<your-org-name>/`).
> 2. Click the **User settings** icon next to your avatar in the top right corner of the page.
> 3. Click **SSH public keys**.
> 4. On the page that displays, click **+ New Key**.
> 5. In the **Add New SSH Key** panel that displays, fill in the following:
>    * **Name** - Enter a descriptive name, such as *Omni Snowflake Model*
>    * **Public Key Data** - Paste the contents of omni\_deploy\_key.pub.
> 6. Click **Add**.

> [tab] Bitbucket Cloud
>
> Bitbucket Cloud access keys are read-only. To allow Omni to push changes, you'll need to add the SSH key to a user account with write access to the repository. We recommend using a service account for this purpose.
>
> 1. Create a service account with write access to the repository.
> 2. In the service account, navigate to **Personal Bitbucket settings > SSH keys**.
> 3. Click **Add key**.
> 4. Fill in the fields as follows:
>    * **Label** - Give your new SSH key a descriptive label
>    * **Key** - Paste the contents of omni\_deploy\_key.pub.
> 5. Click **Add key** to save the key.

> [tab] Bitbucket Data Center
>
> 1. In the Bitbucket repository, click **Repository settings**.
> 2. Click **Access keys**, located in the sidebar.
> 3. Click **Add key**.
> 4. Fill in the fields as follows:
>    * **Key** - Paste the contents of omni\_deploy\_key.pub.
>    * **Permission** - Select **Write** to allow Omni to push changes made in Omni to the repository
> 5. Click **Add key**.

## 3. Supply the private key to Omni with the API

Next, call the [Update Git configuration](https://docs.omni.co/api/model-git-configuration/update-git-configuration.md) API and provide the private key.

> [tab] Unencrypted keys
>
> In the terminal, navigate to the same location where the `omni_deploy_key` file was saved. Then, run the following:
>
> ```bash wrap theme={null}
> curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
>   -H "Authorization: Bearer <YOUR_API_TOKEN>" \
>   -H "Content-Type: application/json" \
>   -d "$(jq -n --arg key "$(cat omni_deploy_key)" '{deployPrivateKey: $key}')"
> ```
>
> Replace the following variables:
>
> * `<your-subdomain>` - Your Omni subdomain
> * `<MODEL_ID>` - The shared model's UUID
> * `<YOUR_API_TOKEN>` - Your Omni API key
>
> A successful response will include the derived public key in the `publicKey` field.

> [tab] Passphrase-protected keys
>
> 1. In the terminal, navigate to the same location where the `omni_deploy_key` file was saved.
> 2. Run the following to create a plain shell variable for the passphrase:
>
>    ```bash wrap theme={null}
>    printf "Passphrase: " && read -rs DEPLOY_KEY_PASSPHRASE && echo
>    ```
> 3. When prompted, enter the passphrase.
> 4. Then, run the following to supply Omni with the private key and passphrase:
>
>    ```bash wrap theme={null}
>    curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
>      -H "Authorization: Bearer <YOUR_API_TOKEN>" \
>      -H "Content-Type: application/json" \
>      -d "$(jq -n \
>            --arg key "$(cat omni_deploy_key)" \
>            --arg passphrase "$DEPLOY_KEY_PASSPHRASE" \
>            '{deployPrivateKey: $key, deployKeyPassphrase: $passphrase}')"
>    ```
>
>    Replace the following:
>
>    * `<your-subdomain>` - Your Omni subdomain
>    * `<MODEL_ID>` - The shared model's UUID
>    * `<YOUR_API_TOKEN>` - Your Omni API key
>
>    A successful response will include the derived public key in the `publicKey` field.
> 5. After you receive a successful response, run the following to unset the passphrase variable:
>
>    ```bash theme={null}
>    unset DEPLOY_KEY_PASSPHRASE
>    ```

> [!TIP]
>
> If you run into issues, see the [Troubleshooting section](#troubleshooting).

## 4. Verify the new key works

To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.

Alternatively, call the [Sync model with Git repository](https://docs.omni.co/api/model-git-configuration/sync-model-with-git-repository.md) endpoint:

```bash theme={null}
curl -X POST https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git/sync \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

If the connection test or sync succeeds, the new key is working correctly.

## 5. Remove the old key from your Git provider

Once you've confirmed the new key works, remove the old deploy key from your Git provider's settings.

## Troubleshooting

> [accordion] 400 error: Invalid key format
>
> The private key must be in PEM format (OpenSSH, PKCS#1, or PKCS#8) and be a valid RSA or ED25519 key. Common causes:
>
> * The key file is corrupted or incomplete
> * The key is in an unsupported format (for example, PuTTY `.ppk` format)
> * The key file contains extra whitespace or characters
>
> Regenerate the key with `ssh-keygen` and try again.

> [accordion] 400 error: Wrong passphrase
>
> The passphrase you provided does not match the passphrase used to encrypt the private key. Verify the passphrase and retry.
>
> If you've forgotten the passphrase, you'll need to generate a new keypair and start the rotation process again.

> [accordion] 400 error: Encrypted key requires deployKeyPassphrase
>
> The private key is passphrase-protected, but you didn't supply `deployKeyPassphrase` in the request. Either:
>
> * Provide the passphrase via the `deployKeyPassphrase` field
> * Or generate a new unencrypted key (press Enter when `ssh-keygen` prompts for a passphrase)

> [accordion] 400 error: deployKeyPassphrase cannot be provided without deployPrivateKey
>
> You included `deployKeyPassphrase` in the request body without `deployPrivateKey`. Remove `deployKeyPassphrase` or include `deployPrivateKey`.

> [accordion] 400 error: deployPrivateKey not supported with authMethod: https\_token
>
> Custom deploy keys are only supported for SSH authentication. If your model uses HTTPS token authentication (`authMethod: https_token`), you cannot supply a custom deploy key. HTTPS token connections rotate via the `token` field instead.
>
> To use custom deploy keys, switch your model to SSH authentication.

> [accordion] Sync fails after rotation
>
> If Git operations fail after rotating the key:
>
> 1. Verify the public key was added to your Git provider with **write access**.
> 2. Verify the public key in the API response matches the public key you added to your Git provider (compare the `publicKey` field in the response to the contents of `omni_deploy_key.pub`).
> 3. Check your Git provider's webhook logs for authentication errors.
>
> If the issue persists, re-add the public key to your Git provider and retry the rotation.

## Next steps

* [Git integration settings](https://docs.omni.co/integrations/git/settings.md) to configure pull request behavior, base branches, and more
* [Git integration overview](https://docs.omni.co/integrations/git) for the full feature set
* [Update Git configuration API reference](https://docs.omni.co/api/model-git-configuration/update-git-configuration.md) for all available fields


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.