Skip to main content

Custom connector

Connect any REST API that is not in the catalog: define its base URL and how it authenticates once, then everyone in your organization can connect to it.

Connect it with: API key. Custom connector's own documentation: https://datatracker.ietf.org/doc/html/rfc6750.

What agents can do​

Connect Custom connector so the agents working your tasks can reach it. With it connected, they can:

  • Call any endpoint of the API with the key you connected, from the base URL you defined.
  • Read records, create or update them and trigger jobs, exactly as the API's own documentation describes.
  • Use the same connection across every task that is allowed to use the secret, without anyone pasting the key into a prompt.

Before you start​

  • The API's documentation, to find its base URL and how it expects the key (Bearer token, a named header such as X-API-Key, HTTP Basic, or OAuth2).
  • A key, token, login or OAuth app for the API.
  • To define a connector the whole organization can reuse: an Org Owner or Admin. Open Secrets, select Add secret, pick the Custom category, then Add custom on the Custom connector card. Give it a name, the base URL and the auth scheme (bearer token, header key, user name and password, or OAuth2 client), and optionally a test path such as /v1/me. Once saved every member sees it as its own card in the Custom category, and connects to it like any built-in service.
  • A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.

Connect with Custom connector​

Jaah connects to Custom connector with an API key, not with a sign-in button.

Connect with an API key​

Find each value first:

  • URL (optional): The API's root address, for example https://api.example.com/v1. It must be https:// and reachable from the internet; Jaah refuses private, loopback and cloud-metadata addresses.
  • API key: The key or token the API gave you, usually under its account, developer or API settings page. Paste the key alone, without a scheme word such as Bearer.
  • Header name (optional): The HTTP header the API reads the key from, as its documentation names it (for example X-API-Key). Leave it blank to send the key in Authorization.
  • Value prefix (optional): The word sent before the key, such as Bearer or Token. Leave it blank to send the key alone.

Then add it to Jaah:

  1. In Jaah, open Secrets, select New, and pick the Custom connector card.
  2. Name the secret and choose who can use it.
  3. Fill in URL, API key, Header name, Value prefix.
  4. Select Save. Jaah tests the secret straight away (see Test the connection).

Jaah encrypts what you type and never shows it again — not to you, and not to an admin.

Use your own OAuth app​

Not used: Jaah connects to Custom connector with an API key, not through an OAuth app.

Test the connection​

Select Test on the secret. Jaah makes one read-only call to Custom connector with the stored values and shows the result on the secret's page. Jaah also tests automatically when you save or reconnect.

Who can use it​

Every secret has an owner, and the owner decides who can use it:

  • Personal — only your own tasks can use it. This is the default.
  • Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
  • Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.

More on owners and access: How secrets work.

Use it in an agent session​

An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:

  • org/<name> for an organization secret,
  • projects/<project>/<name> for one attached to a project,
  • me/<name> for your personal one.

A key connection hands the agent its fields: base_url, api_key, header_name, value_prefix.

Tell the agent in your task description which secret to use, for example “use the Custom connector secret org/custom-connector”.

Manage, rotate or disconnect​

Everything is on the secret's page under Secrets:

  • Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at Custom connector once the test passes. Steps: Replace or delete a secret.
  • Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at Custom connector's side too, revoke or delete the key at Custom connector.

Limitations​

  • Jaah does not know the API's endpoints: agents work from the API's own documentation, so link it in the task or the connector's description.
  • The Test calls one GET request on the test path (or the base URL when there is none) and passes on any 2xx answer, so it proves the API accepted the secret, not that every endpoint will.
  • Only https:// addresses on the public internet can be defined; an API inside a private network is not reachable from Jaah's control plane.
  • An OAuth2 connector needs an OAuth app you register at the API's provider, with the redirect URI shown on the connection's page.
  • Agents can do only what the connected Custom connector account allows.

Troubleshooting​

Saving the connector says the Base URL is refused

The host resolves to a private, loopback or cloud-metadata address, or it is not https. Use the API's public https address.

The Test says the host rejected the request (401 or 403)

Check the key, then the connector's header name and value prefix against the API's documentation. Many APIs expect X-API-Key with no prefix, others Authorization with Bearer.

The Test says the host answered 404

The test path does not exist on the API. Ask an Org Owner or Admin to set a test path the API answers, such as /v1/me or /health.

The Test cannot reach the address

Check the base URL is spelled correctly and the API is online; Jaah dials only public addresses.

Still stuck? Select Test and read the result: it names the value Custom connector refused and the status it answered.

FAQ​

What is the difference between this card and a built-in service?

A built-in service knows its own address, auth and test. A custom connector is the same thing defined by your organization: you supply the address, auth scheme and test path once, and every member then connects to it on its own card under Secrets > Add secret > Custom.

Can another organization see our custom connectors?

No. A custom connector belongs to the organization that defined it; other organizations never see it.

Who can change or delete a custom connector?

Org Owners and Admins. A connector that still has connections cannot be deleted, so nobody loses a working secret by accident.

Can Jaah or an admin see the key or token?

No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.

Can I connect more than one Custom connector account?

Yes. Add one secret per account, each with its own name, and tell the agent which one to use.