Skip to main content

Authentication for API Tools

Most real APIs need credentials. Orki's Authentication providers let you store a credential once — an API key or an OAuth2 client — and attach it to any API tool or workflow step. On every call, Orki injects the credential on the server, just before the request leaves the platform.

The important part: the AI agent never sees the credential. It isn't in the tool schema, the prompt, or the response the agent reads. Secrets are encrypted at rest.

For Balloon Bliss, the shop's order API requires an API key — we'll store it as a provider called balloon_orders_key and attach it to the order_status_lookup tool.

Where to Find It​

Integrations → Authentication in the sidebar.

Authentication list

Each card shows the credential type and where it's injected. Click New authentication to create one.

Two Credential Types​

TypeHow it worksUse it for
Static API keyA fixed secret injected into a header or query parameter on every call.X-Api-Key-style APIs, personal access tokens.
OAuth2 client credentialsOrki exchanges your client ID + secret for a bearer token at the provider's token URL, caches it, refreshes it before expiry, and injects Authorization: Bearer ….Partner APIs with an OAuth2 client_credentials flow.

Example 1 — Static API Key​

  1. Name — balloon_orders_key. Internal label (snake_case); the agent never sees it.
  2. Pick the Static API key card.
  3. Inject into — Header, Header name — X-Api-Key.
  4. Key value — paste the secret.
  5. Optional Value prefix — e.g. Bearer if the API expects Authorization: Bearer <key>.

The preview at the bottom shows exactly what will be added to each call — e.g. Header: X-Api-Key = ••••••.

Static API key form

Click Save.

Example 2 — OAuth2 Client Credentials​

Say Balloon Bliss later integrates a shipping partner whose API uses OAuth2:

  1. Name — shipping_partner_oauth, pick the OAuth2 client credentials card.
  2. Token URL — the partner's token endpoint (e.g. https://api.shipping-partner.example/oauth/token).
  3. Client ID / Client secret — from the partner.
  4. Scope (optional) — space-separated, e.g. shipments.read shipments.write.
  5. Send credentials as — Form (default) or JSON, matching what the token endpoint expects.

OAuth2 client credentials form

The Advanced section covers non-standard providers: where to read the token from the response (JSONPath), expiry handling, custom injection, and extra token-request fields. The defaults fit the standard OAuth2 flow.

Tokens are cached and refreshed automatically — your API tools don't deal with expiry at all.

Attaching to a Tool​

Open the tool (Integrations → APIs → Edit) and pick the provider in its Authentication section:

Tool with auth provider attached

That's it. Every execution of this tool — whether the agent calls it directly or a workflow step runs it — now goes out with the credential injected. One provider can back any number of tools, and rotating the secret in one place updates them all.

Security Notes​

  • Secrets are encrypted at rest and decrypted only at the moment of the outbound call.
  • The agent-facing tool schema and results contain no trace of the credential — a prompt-injection attempt can't ask the agent to reveal what it never had.
  • Prefer a provider over pasting keys into a tool's header fields: header values live in the tool config, while provider secrets are write-only after saving.

Troubleshooting​

  • 401/403 from the external API — the key is wrong or lacks permissions; edit the provider and re-enter the key value.
  • OAuth2 tool calls fail after working earlier — check the token URL is still reachable and the client wasn't revoked; Orki fetches a fresh token automatically once the cached one is rejected or expires.
  • Which tools use this provider? Open each tool's Authentication section — deleting a provider that's still attached will break those tools' calls.

Next Steps​