External Credential Connection

Overview — what it is

External Credential Connection is another way to get a new data source set up in NinjaCat. Instead of your team authenticating a network from inside the NinjaCat UI, you generate a secure, single-use link and send it to the person who owns the credentials. They open the link, sign in to their data provider (for example Google Ads or CallRail), and the credential appears in your NinjaCat account when they finish — without them ever logging in to NinjaCat and without them sending you their credentials.

This is useful whenever the data lives with someone outside your team: a client, a partner, or a colleague who holds the provider login but shouldn't have NinjaCat access. The link is single-use and expires.

Who it's for and when to use it

Use an External Credential Connection when:

• A client holds the login for the data source and you'd rather not collect their password or screen-share through a setup.
• You want to onboard a new data source without walking the client through the in-platform connection steps.
• You need to reconnect an existing credential that has expired or lost authorization — the client can re-authorize it themselves from a link, and the credential is updated in place.

It's the self-service alternative to connecting a network inside NinjaCat yourself.

Prerequisites

• Agency Management API access. External Credential Connection is driven through NinjaCat's Agency (Organization) Management Open API. Your agency needs API access enabled. If you don't see an Apps tab on your agency settings screen, contact your NinjaCat Account Manager to request access.
• API credentials from the Apps tab. Under agency settings → Apps you'll find your Client ID, Client Secret, and Agency Identifier Key.
• An access token. The credential-link endpoints authenticate the same way as every other Management Open API endpoint:
  1. Call POST /oauth2/token with Authorization: Basic base64(client_id:client_secret) to get an access token.
  2. On every credential-link request, send these headers:
     • Authorization: Bearer <access_token>
     • Client-Id: <client_id>
     • x-api-key: <Agency Identifier Key>
     • Accept: application/json
     • Content-Type: application/json

Two ways to start a link

From the NinjaCat UI (reconnect only). Go to Data Sources → More Actions → "Request new credentials from client." This mints a reconnect link for an existing credential so the client can re-authorize it. New connections are API-only for now — there isn't yet a UI button to create a brand-new data source this way.

From the API (new connections and reconnects). Create the link with the Management Open API, as described below.

How it works, step by step (API)

For the complete request and response reference, see the Credential Link (Network Link) section of the NinjaCat Agency Management API documentation.

1. Create a credential link

POST /management_open_api/credential_links

Headers: Authorization: Bearer <access_token>, Client-Id, x-api-key: <Agency Identifier Key>, Content-Type: application/json, Accept: application/json.

Body:

• Which data source — the provider's class_name (e.g. google_adwords, call_rail_v2) or its network_definition_id (same ids as the Networks endpoints). Provide exactly one of the two.
• label (required, 1–255 characters) — the credential's name in your account. For a reconnect, you still send a label, but the credential's existing name is kept.
• purpose (optional) — new_connection (default) or reconnect.
• network_id — required for a reconnect (the existing credential to re-authorize) and forbidden otherwise. It must belong to your account and to the same provider.
• ttl_seconds (optional) — link lifetime. Default 86400 (24 hours); minimum 300 (5 minutes); maximum 2592000 (30 days).
• redirect_uri (optional) — where to send the client after they finish (see "Redirect the client when they're done," below).

A successful call returns 201 with the link object, including a url. Only this create call ever returns the url — treat it like a password, and send it to the client. If your account has a white-label domain configured, the URL is issued on that domain.

Minting a reconnect link expires any earlier pending reconnect link for the same credential — only one valid link exists per credential at a time.

2. The client completes authentication externally

The link opens a page branded with your agency name and logo. The client does not log in to NinjaCat, doesn't need a NinjaCat account, and never sees your NinjaCat account or any existing credential's values.

• OAuth providers (Google, Facebook, etc.): the client clicks Continue and signs in with the provider.
• Key / password providers: the client enters only the fields that provider needs, and the values are validated with the provider before they're saved.

The link is single-use and can be attempted at most 10 times against the provider before it's retired.

3. Check the status

GET /management_open_api/credential_links/{id} returns the same object without the url.

• pending — not used yet and not expired.
• used — the client completed it. network_id is the credential that was created or re-authorized; used_at / used_at_local say when.
• expired — the link lapsed, was superseded by a newer reconnect link for the same credential, or was retired after too many failed attempts. Mint a new one.

Times ending in _local are in your agency's timezone (shown as timezone); all other timestamps are UTC in ISO 8601 format.

Redirect the client when they're done (optional)

When you create a link you can set an optional redirect_uri — an absolute https:// URL. On successful completion, NinjaCat sends the client's browser to that URL with these query parameters appended:

• credential_link_id
• network_id
• status=completed

This lets you return the client to your own "all set" page. If you don't set a redirect_uri, the client simply sees NinjaCat's branded "You're connected" page.

What happens afterward in NinjaCat

Once the client completes the link, the credential lives in your account like any other:

• It shows a "Client connected" tag in Data Sources (a status marker indicating the credential was connected by a client via a link).
• Its secret fields are read-only until an admin chooses to edit them.
• For a reconnect, the existing credential is updated in place — nothing new is created.
• You can then attach the credential to a dataset so it starts pulling data. Attaching applies to every dataset on that connector configuration, and you can optionally start a backfill for a date range at the same time.

Finding it later. Separately from the "Client connected" status tag, the label you set when creating the link becomes the credential's tag, which is searchable through the Networks endpoint's tag filter. Give each link a recognizable label (for example a client name or reference) and you can later retrieve that credential by filtering networks on the tag.

Limitations & FAQ

Is the link reusable?
No. Each link is single-use and expires. For reconnects, minting a new link also expires any earlier pending reconnect link for that credential.

How long does a link last?
Whatever you set (ttl_seconds), defaulting to 24 hours. Range: 5 minutes to 30 days.

Does the client need a NinjaCat login?
No. They authenticate with the data provider only, on a page branded with your agency's name and logo.

Can I create a brand-new connection from the UI?
Not yet — the UI option ("Request new credentials from client") is for reconnects. New connections are created through the API.

Which data sources can't be connected this way?
Link creation is rejected for providers that can't be connected through a link — for example alias providers (such as facebook_insights, which points you to the real provider), providers with no credential inputs, providers that aren't currently available, and configurable OAuth providers that don't have OAuth app credentials set up on your account. The error message says which.

What if the client's authorization expires later?
Mint a reconnect link for that credential (via the UI or API) and send it to them; they re-authorize from the link without you touching their login.

What the errors mean

• 422 — Something in the request is off. A missing or invalid field; sending both or neither of class_name / network_definition_id; a ttl_seconds out of range; a network_id on a new connection; a network_id that belongs to a different provider; or a provider that can't be connected via a link. The message tells you which.
• 404 — Not found in your account. The network_id you referenced doesn't exist in your account.
• 401 — Not authenticated. Your access token is missing or expired; get a fresh one from POST /oauth2/token.