Credentials

There are two distinct credential surfaces in Traces, and it's important not to confuse them:

1. The credential upload form (/analyst/credentials/new) — uploads a production credential for a customer. Once saved you can never view it again; it's encrypted at rest.
2. The test-credentials form — lives inside the connector/endpoint editor and exists only to test a connector against a real (usually test) account while building it. These use the slot model and live with the connector, not a customer.

This page covers both.

---

Credential upload form

Route: /analyst/credentials/new

Used to upload a credential securely on a customer's behalf. The page is split into two cards.

Customer Selection card

• Upload on behalf of customer toggle (on by default for analysts). When on, a yellow notice warns that the customer will receive an email notification and that you will not be able to view the credential value after submission.
• Customer dropdown (required when on-behalf-of). Selecting one shows a confirmation block with the company, contact, and email.
• Reason for On-Behalf-Of Action (required, minimum 10 characters) — included in the customer's email notification.

Credential Details card

• A green security note reiterates that the credential is encrypted and unreadable after submission.
• Connector and Credential Type selectors. Picking a connector defaults the credential type to that connector's configured auth type.
• Dynamic fields that change with the credential type.
• A Test Connection section (appears once a type is chosen) to validate the credential before saving.

Only production connectors and verified customers appear in the dropdowns. Submitting POSTs to /api/credentials, shows a success toast, and returns you to the Collections list.

---

Test-credentials form (slot model)

This form is embedded in the connector editor (it is not a standalone page). It lets you enter and test credentials against the connector you're building.

The slot model

A connector can hold multiple named credential slots — for example separate test accounts, or one of each auth type. Each slot has:

• A label (editable name)
• A credential type
• The stored secret values
• An optional persistent flag

One slot at a time is the active slot — the one used when the connector runs a test. The footer exposes Delete, Update (save), and Use / Update & Use (save-and-activate) actions. Clicking Use on an already-saved, unchanged slot activates it without re-saving.

Choosing a credential type

Types are grouped Standard and Advanced:

Group	Type	Use for
Standard	Custom Request	Freeform auth flow; variables are collected from the connector's auth request template
Standard	OAuth 2.0	Authorization-code or client-credentials flows with token refresh
Standard	API Key	A static key sent in a header or query parameter
Standard	Bearer Token	A JWT/opaque token sent as Authorization: Bearer …
Standard	Basic Auth	Username + password (some APIs use the API key as the username)
Advanced	Token Exchange	POST to a token endpoint before each request to mint an access token
Advanced	Query Params	Auth credentials passed as URL query parameters (e.g. Trello)
Advanced	Client Certificate	mTLS client cert + private key in PEM format

When the connector ships a credential guide, a collapsible "How to get credentials for {platform}" panel appears with prerequisites, numbered steps, links to the developer portal, and notes.

Per-type fields

Every secret field has a show/hide eye toggle and is annotated so password managers don't auto-fill it.

• API Key — key value, optional header name (blank uses the auth config's header name).
• Bearer — the token.
• Basic — username/API key and an optional password.
• OAuth 2.0 — access token and optional refresh token, plus the authorization-code step below.
• Query Params — repeatable key/value pairs appended to every request URL.
• Token Exchange — token endpoint URL/method/content-type, endpoint authentication (client ID/secret, bearer, or API key), response mapping (JSON path to the access token), token application (header vs query), and an authorization code if the grant requires one. A "I already have an access token" field bypasses the exchange entirely.
• Custom Request — one input per {{variable_name}} placeholder found in the connector's auth request template. Values are substituted at runtime. If the template has no placeholders, no input is needed.
• Client Certificate — certificate (PEM), private key (PEM, blurred until revealed), and optional passphrase.

OAuth code exchange at test time

For OAuth 2.0 and token-exchange types that need an authorization code, the form builds the authorization URL from the connector's OAuth flow config (resolving {{variable}} templates):

1. Click Open — the authorization URL opens in a centred popup.
2. Authorize in the popup. On the callback, the popup postMessages the code back and the form captures it automatically — a green "Code applied — ready to save" confirmation appears.
3. Alternatively, paste the full callback URL into the Callback URL field and the form extracts the code parameter for you.

warning

Authorization codes are short-lived — roughly 5 minutes. Save and run a test immediately after capturing one, or it will expire before the exchange completes.