Private API (Generic)

Overview

Pre-built tooling

Pre-built integrations

Access requirements

Setup guide

Useful links

API gotchas

Pre-built tooling

✅ Authorization

Tools	Status
Pre-built authorization (API Key)	✅
Pre-built authorization UI	✅
Custom authorization UI	✅
End-user authorization guide	✅
Expired credentials detection	✅

✅ Read & write data

Tools	Status
Pre-built integrations	🚫 (time to contribute: <48h)
API unification	✅
2-way sync	✅
Webhooks from Nango on data modifications	✅
Real-time webhooks from 3rd-party API	🚫 (time to contribute: <48h)
Proxy requests	✅

✅ Observability & data quality

Tools	Status
HTTP request logging	✅
End-to-end type safety	✅
Data runtime validation	✅
OpenTelemetry export	✅
Slack alerts on errors	✅
Integration status API	✅

✅ Customization

Tools	Status
Create or customize use-cases	✅
Pre-configured pagination	🚫 (time to contribute: <48h)
Pre-configured rate-limit handling	🚫 (time to contribute: <48h)
Per-customer configurations	✅

No pre-built syncs or actions available yet.

Not seeing the integration you need? Build your own independently.

When to use it

Use Private API (Generic) for APIs that authenticate with an API key but do not use Authorization: Bearer <key>. Unlike Private API (Bearer Auth), you configure per integration how the proxy presents the key:

Key placement: header or query param. Prefer header — keys sent as a query param can be exposed in upstream, proxy, and CDN logs.
Key name: the header or query-param name, e.g. Authorization, x-api-key, api_key.
Value template: how the key is wrapped, using ${apiKey} as the placeholder, e.g. ${apiKey}, Bearer ${apiKey}, Api-Key ${apiKey}.
Base URL: the upstream API the proxy calls.
API key label: the label end users see for the key field in the Connect UI.

The key is vaulted by Nango and injected by the proxy, so raw credentials never need to leave Nango.

Important limitations

Limited functionality: Private API (Generic) is limited to storing and injecting a single API key. Because it’s generic, many advanced Nango features are not available for it.
Base URL required: You must set the base URL on the integration; there is no predefined base URL like other integrations.
Recommended use cases only: The only recommended use case for private API integrations is to store credentials for internal/customer-specific APIs that cannot be added to the Nango catalog.
For all other use cases: We recommend contributing the API to Nango or requesting it be added by us.

Create the integration programmatically

You can create and update a Private API (Generic) integration from the dashboard, or programmatically with the API or SDK by passing its configuration in integration_config.

await nango.createIntegration({
    provider: 'private-api-generic',
    unique_key: 'acme-internal',
    display_name: 'Acme Internal API',
    integration_config: {
        baseUrl: 'https://api.acme.com',
        keyPlacement: 'header',
        keyName: 'Authorization',
        valueTemplate: 'Api-Key ${apiKey}',
        keyLabel: 'Acme API Key'
    }
});

curl -X POST 'https://api.nango.dev/integrations' \
  -H 'Authorization: Bearer <NANGO-API-KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "private-api-generic",
    "unique_key": "acme-internal",
    "display_name": "Acme Internal API",
    "integration_config": {
      "baseUrl": "https://api.acme.com",
      "keyPlacement": "header",
      "keyName": "Authorization",
      "valueTemplate": "Api-Key ${apiKey}",
      "keyLabel": "Acme API Key"
    }
  }'

Configuration fields:

Field	Required	Description
`baseUrl`	Yes	Base URL of the upstream API the proxy calls.
`keyPlacement`	Yes	Where the API key is sent: `header` or `query`. Prefer `header`.
`keyName`	Yes	Header or query-param name, e.g. `Authorization`, `x-api-key`.
`valueTemplate`	Yes	How the key is presented, using `${apiKey}` as the placeholder, e.g. `Api-Key ${apiKey}`.
`keyLabel`	No	Label end users see for the key field in the Connect UI. Defaults to `API Key`.

To change the configuration later, send the fields you want to update with Update an integration (PATCH /integrations/{uniqueKey}) or nango.updateIntegration().

Setup guide

No setup guide yet.

Need help getting started? Get help in the community.

Contribute improvements to the setup guide by editing this page

Useful links

No useful links yet.

Contribute useful links by editing this page

API gotchas

Contribute API gotchas by editing this page

Connect to Private API (Generic)

Guide to connect to Private API (Generic) using Connect UI

​Overview

Pre-built tooling

Pre-built integrations

Access requirements

Setup guide

Useful links

API gotchas

​Pre-built tooling

​When to use it

​Important limitations

​Create the integration programmatically

​Setup guide

​Useful links

​API gotchas

Connect to Private API (Generic)

Overview

Pre-built tooling

When to use it

Important limitations

Create the integration programmatically

Setup guide

Useful links

API gotchas