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. The current credential keeps working the whole time, right up until the client finishes the link.

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 Organization 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: <Organization 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. The UI route uses fixed settings: the link always lasts 24 hours, has no redirect, and uses the credential's current name as its label. 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, when you want to set the lifetime, add a redirect, choose a label, or create a brand-new connection.

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: <Organization 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. A new-connection OAuth link always creates a brand-new credential; it never merges into an existing credential that uses the same provider login.

2. The client completes authentication externally

The link opens a page branded with your agency name (and logo, if you've set one). 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. Where the provider supports an instant check, the values are verified before they're saved and the client sees a "You're connected" confirmation. Some providers can't be checked on the spot — there the values are saved as entered, and the client sees "Details saved", noting that your agency will confirm the connection on its first data pull.

The link is single-use. For key/password providers, it's retired after 10 submissions (the counter only advances when the client submits the form). OAuth attempts aren't counted.

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. (Briefly, while a completion is still finishing, the status can read used with network_id still null; if that completion fails, the link returns to pending.)
  • expired — the link lapsed, was superseded by a newer reconnect link for the same credential, or was retired after too many submissions. Mint a new one.

Timestamps ending in _local are rendered in your agency's timezone and human-readable (for example, "4 Nov 2026, 3:00 PM EST"); 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. On successful completion, NinjaCat sends the client's browser to that URL with these query parameters appended:

  • credential_link_id
  • network_id
  • status=completed

A few rules for the URL: it must be https:// (plain http:// is allowed only for localhost, for testing), can't contain a # fragment or a username/password, and is capped at 2,048 characters. Any query parameters already on the URL are preserved, and the redirect only fires when the link completes successfully.

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 own confirmation page — "You're connected" when the credential was verified, or "Details saved" when it will be confirmed on the first data pull.

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, marking that it was connected by a client via a link.
  • For key / password credentials, the secret fields are read-only until an admin chooses to edit them. OAuth credentials have no secret fields to lock, so that step doesn't apply to 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" tag, the label you set when creating the link becomes the credential's tag, which is searchable through the Networks endpoint's tag filter. The filter matches the whole tag, ignores case, and supports * as a wildcard (for example, tag=Acme*). Give each link a recognizable label — a client name or reference — and you can retrieve that credential later by filtering 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. Links created from the Data Sources UI always last 24 hours.

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, if you've set one).

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. The existing credential keeps working until they finish.

What the errors mean

Error responses come in two shapes: 422 and 404 return {"message": "..."}, while 401 returns {"errors": [...]}.

  • 422 — Something in the request is off. A missing or invalid field; sending both or neither of class_name / network_definition_id; an unknown provider (a class_name or network_definition_id that doesn't exist); 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 — or, when reading a link, the credential link id doesn't exist in your account.
  • 401 — Not authenticated. Your access token is missing or expired, or the Client-Id header is missing. Get a fresh token from POST /oauth2/token and make sure both headers are set.

Did this page help you?