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

# Deploy a custom API and connector

> Deploy your connector and publish your API through Azure API Management with pull requests to your applications-live repository.

After you build a custom connector, and optionally a custom API, you deploy the connector and any custom API through pull requests to your DevHub `applications-live` repository. ArgoCD applies the changes. There's no manual publishing: every API, unified or custom, is published through `applications-live`.

The following diagram shows how a release becomes a running connector and a published API:

```mermaid theme={"system"}
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#ffffff',
    'primaryBorderColor': '#295eff',
    'primaryTextColor': '#091c35',
    'lineColor': '#091c35',
    'secondaryColor': '#f3f6f9',
    'tertiaryColor': '#ebf0f5',
    'fontFamily': 'Libre Franklin, sans-serif'
  }
}}%%
flowchart LR
  subgraph Build["Build"]
    A["API repository release"] --> C["API Helm chart in<br/>your container registry"]
    B["Connector repository release"] --> D["Connector image and Helm chart in<br/>your container registry"]
  end
  subgraph Deploy["Deploy"]
    E["Pull request to<br/>applications-live"] --> F["ArgoCD sync"]
    F --> G["Connector running on<br/>Azure Kubernetes Service"]
    F --> H["API, product, and subscription in<br/>Azure API Management"]
  end
  C --> E
  D --> E
```

## Prerequisites

Before you begin, make sure you have:

* A released connector repository. For more information, see [Overview](/platform/developer-guides/build/overview).
* A released API repository, if you use a custom API. For more information, see [Create a custom API](/platform/developer-guides/get-started/create-custom-api).
* Write access to `gc-devhub-{installation}-applications-live` through the `applications-live` GitHub team.
* The `{env}-apim-rw` and `{env}-apim-subs-ro` roles for your runtime in `self-service.tfvars`.

## Plan your resource names

All workloads, both Backbase-managed and yours, share the same cluster and Azure installation. Prefix the name of everything you create so that each name is unique and identifiable.

Release names must be unique for each deployed version and follow the pattern `{name}-v{major}`. Avoid tokens such as `temp`, `poc`, or environment names in release names.

<Warning>
  A name that isn't unique can collide with resources from other workloads in the same installation. Choose and apply your prefix before you create the first resource.
</Warning>

The following table lists the resources you create and an example name:

| Resource | Example name | Defined in |
| - | - | - |
| Connector release | `yourprefix-onboarding-v1` | `runtimes/{runtime}/apps/` |
| API | `yourprefix-onboarding-api` | `runtimes/{runtime}/apim/apis/` |
| Version set | `yourprefix-onboarding-api` | `apiversionsets.values.yaml` |
| Backend | `yourprefix-onboarding-backend` | `backends.values.yaml` |
| Product | `yourprefix-onboarding-product` | `products.values.yaml` |
| Subscription | `yourprefix-onboarding-subscription` | `subscriptions.values.yaml` |

## Deploy the connector

When you release a connector repository, the build creates a container image and a Helm chart, and pushes both to your installation's container registry. Snapshot charts use the version `{version}-{sha8}`. `applications-live` references the chart version.

To deploy the connector, open a pull request that:

* Adds your connector release to `runtimes/{runtime}/apps/` as an ArgoCD `Application`, with one source for each release and the chart taken from your registry.
* Adds your values under `runtimes/{runtime}/values/`.

After you merge the pull request, ArgoCD syncs automatically. For more information, see [Configure connectors](/banking-os-connectors/configure-connectors) and [Run](/platform/developer-guides/run).

DevHub workloads run in a DevHub namespace. The default namespace is `devhub-grandcentral`. For a dedicated namespace, use `devh-gc-<domain>`. You use this namespace in the connector URL. For more information, see [Deployment namespace](/platform/developer-guides/run#deployment-namespace).

The URL of the deployed connector follows this pattern, and you use it as the backend URL in the next section: `https://{releaseName}-{namespace}.{runtime}.{installation}.gcservices.io`.

## Publish the API

You configure the API in `runtimes/{runtime}/apim/` of your `applications-live` repository. Replace `YOUR_API` with the artifact ID of your API repository. For a description of each field, see [Azure API Management configuration](/platform/developer-guides/get-started/configuring-apim).

To publish the API, follow these steps:

1. **Register the API.** Create the file `runtimes/{runtime}/apim/apis/YOUR_API.yaml`. It's an ArgoCD `Application` with two sources: your `applications-live` repository, and the API Helm chart from your container registry.

   ```yaml theme={"system"}
   apiVersion: argoproj.io/v1alpha1
   kind: Application
   metadata:
     name: YOUR_API
     namespace: argocd
   spec:
     project: YOUR_ARGOCD_PROJECT
     destination:
       server: https://kubernetes.default.svc
       namespace: YOUR_NAMESPACE
     sources:
       - repoURL: git@github.com:bb-ecos-INSTALLATION/gc-devhub-INSTALLATION-applications-live.git
         targetRevision: main
         ref: apps-live
       - repoURL: YOUR_ACR/charts
         chart: YOUR_API
         targetRevision: CHART_VERSION
         helm:
           releaseName: YOUR_API-v1
           valueFiles:
             - $apps-live/runtimes/RUNTIME/apim/apis/common.apim.values.yaml
     syncPolicy:
       automated:
         prune: true
         selfHeal: true
   ```

   Set `CHART_VERSION` to the chart version from the build of your API repository. The `apimArmId` value comes from `common.apim.values.yaml`, so you don't set it for each API. Copy `YOUR_ARGOCD_PROJECT` from an existing API application in your installation. `YOUR_NAMESPACE` is commonly `devhub-grandcentral`, or `devh-gc-<domain>` for a dedicated namespace. For more information, see [Deployment namespace](/platform/developer-guides/run#deployment-namespace).

2. **Add the version set.** Add your API to `apiversionsets.values.yaml`. Use the same name as `metadata.name` in your API application.

   ```yaml theme={"system"}
   apiVersionSets:
     - name: YOUR_API
   ```

3. **Add the backend.** Add the connector backend to `backends.values.yaml`. The URL is the connector URL from the previous section.

   ```yaml theme={"system"}
   backends:
     - name: YOUR_CONNECTOR_BACKEND
       url: 'https://YOUR_RELEASE-YOUR_NAMESPACE.RUNTIME.INSTALLATION.gcservices.io'
       title: "Your connector v1"
   ```

4. **Create the product.** Add the product to `products.values.yaml`. The API name is `YOUR_API-1`, which is `{artifactId}-{major}`. The policy routes calls for that API to your backend.

   ```yaml theme={"system"}
   products:
     - name: YOUR_PRODUCT
       displayName: "Your product"
       approvalRequired: "false"
       policy:
         apiBackend:
           - api: YOUR_API-1
             backend: YOUR_CONNECTOR_BACKEND
         value: |
           <policies>
             <inbound>
               <base />
               <set-backend-service backend-id="YOUR_CONNECTOR_BACKEND" />
             </inbound>
             <backend><base /></backend>
             <outbound><base /></outbound>
             <on-error><base /></on-error>
           </policies>
       productApis:
         - apiName: YOUR_API-1
   ```

5. **Create the subscription.** Add the subscription to `subscriptions.values.yaml`. Azure API Management (APIM) generates the subscription key from it.

   ```yaml theme={"system"}
   subscriptions:
     - name: YOUR_SUBSCRIPTION
       productScope: YOUR_PRODUCT
   ```

6. **Open the pull request.** Commit the changes and open a pull request. By default, all members of the `applications-live` team are reviewers. After review, merge the pull request. ArgoCD applies the changes.

Some resources depend on others. Backends and named values must exist before the policy fragments that reference them. Secrets must exist before the resources that use them.

To reuse policy logic, define policy fragments in `policyfragments.values.yaml` under `policyFragments`, with a `name` and a `policyValue`. Reference a fragment from a product policy with `<include-fragment fragment-id="YOUR_FRAGMENT"/>`.

## Choose how callers authenticate

Each subscription is scoped to one product and gives callers one key. Choose the setup that fits your callers:

* **Separate key for your custom connector**: Create your own product and subscription, as in the preceding steps.
* **One key for Backbase-managed and custom connectors**: Ask the Backbase implementation team. Managed products live in the Backbase-managed repository, which you can't change.

<Note>
  To read subscription keys in the Azure portal, you need the `{env}-apim-subs-ro` role.
</Note>

## Understand what you can change

You control everything you create in DevHub:

* Custom APIs and custom connectors.
* Products and subscriptions.
* Policies and policy fragments. Your policies can include fragments that are already defined.

You can't change unified APIs or Backbase-managed connectors, and they don't appear in your DevHub repositories.

Standard customers can't change the `repoURL` of an API application. Only premium customers can use custom registries to publish and deploy their own integrations.

For more information, see [GitHub organization and repository structure](/platform/platform-administration/repository-structure).

## Verify the deployment

After ArgoCD syncs, call your API through the gateway with your subscription key in the `api-key` header:

```bash theme={"system"}
curl --location 'https://api.RUNTIME.INSTALLATION.gcservices.io/YOUR_DOMAIN/YOUR_SERVICE/v1/YOUR_PATH' \
  --header 'api-key: YOUR_SUBSCRIPTION_KEY'
```

For more information about calling an API with a subscription key, see [Request Template Connector API](/platform/developer-guides/get-started/request-template-connector-api).

## Promote to other runtimes

To promote your connector and API, repeat the same changes with the same chart versions in the next runtime folder, including the APIM entries. After review and merge, ArgoCD syncs. Don't let a higher runtime run a later chart version than the lower runtimes. For more information, see [Promote to a higher runtime](/platform/developer-guides/run#promote-to-a-higher-runtime).

## Related topics

* [Azure API Management configuration](/platform/developer-guides/get-started/configuring-apim)
* [API management](/platform/api-management)
* [Create a custom API](/platform/developer-guides/get-started/create-custom-api)