Connections

Connections store API credentials and inject them into your tools as environment variables. Create a connection once, reference it in any number of tools. This makes tools portable — sharing a tool just means the recipient creates their own connection with the same name.

Auth Types

Managed Connections (Recommended)

The fastest way to connect a service. One command starts an OAuth flow — you authorize in your browser, and Kyew handles token storage, refresh, and injection.

tool(action="conn_connect", provider="github")
tool(action="conn_connect", provider="google", bundles=["analytics", "search-console"])
tool(action="conn_connect", provider="slack")
tool(action="conn_connect", provider="linear")

Supported Providers

Managed connections auto-refresh OAuth tokens on every tool execution. No manual token rotation needed.

Manual Connections

For services without managed OAuth, create connections manually.

API Key

connection(action="create",
  name="my-github",
  provider="github",
  auth_type="api_key",
  api_key_config={
    key: "ghp_xxxxxxxxxxxxxxxxxxxx",
    header_name: "Authorization",
    prefix: "Bearer "
  })

Bearer Token

connection(action="create",
  name="my-api",
  provider="custom",
  auth_type="bearer",
  api_key_config={
    key: "your-token-here"
  })

Basic Auth

connection(action="create",
  name="my-service",
  provider="custom",
  auth_type="basic",
  basic_auth_config={
    username: "user",
    password: "pass"
  })

OAuth2

connection(action="create",
  name="my-github-oauth",
  provider="github",
  auth_type="oauth2",
  base_url="https://api.github.com",
  oauth_config={
    client_id: "your-client-id",
    client_secret: "your-client-secret",
    auth_url: "https://github.com/login/oauth/authorize",
    token_url: "https://github.com/login/oauth/access_token",
    scopes: ["repo", "read:user"]
  })

Secret URL

Secrets entered in the chat are visible in your conversation history. Use secret_url to enter credentials securely in the browser instead:

connection(action="secret_url", connection_id="my-github")

This returns a secure, one-time browser link. Open it, enter your API key or token, and it's saved directly to the connection. The secret never appears in the chat.

This is the recommended approach for API keys and tokens.

OAuth2 Flow

OAuth2 connections require an authorization step after creation:

1. Create the Connection

connection(action="create",
  name="my-github-oauth",
  provider="github",
  auth_type="oauth2",
  oauth_config={
    client_id: "your-client-id",
    client_secret: "your-client-secret",
    auth_url: "https://github.com/login/oauth/authorize",
    token_url: "https://github.com/login/oauth/access_token",
    scopes: ["repo"]
  })

2. Authorize

connection(action="authorize", connection_id="my-github-oauth")

This returns a URL. Open it in your browser, grant access, and the callback saves the tokens.

3. Connection is Active

After authorization, the connection is active. OAuth tokens are automatically refreshed on every tool execution — you never need to re-authorize unless the refresh token expires.

Provider Templates

List pre-configured provider templates to see auth URLs, scopes, and documentation links:

connection(action="list", templates=true)

Templates are available for common services like GitHub, Google, Slack, and others. They pre-fill the OAuth URLs and suggest scopes, so you only need to supply your client credentials.

Environment Variable Injection

When a tool references a connection via connection_id (for http_proxy tools) or connection_ids (for code tools), credentials are injected as environment variables.

For each connection, three variables are set:

The connection name is uppercased with non-alphanumeric characters replaced by underscores. For example, a connection named my-github produces:

• KYEW_CONN_MY_GITHUB_TOKEN
• KYEW_CONN_MY_GITHUB_BASE_URL
• KYEW_CONN_MY_GITHUB_AUTH_HEADER

Using Connections in Code Tools

Add connection_ids to your code tool's code_config:

tool(action="create",
  name="github_repos",
  description="List my GitHub repositories",
  tool_type="code",
  code_config={
    code: `
export default {
  async fetch(request) {
    const res = await fetch("https://api.github.com/user/repos?sort=updated&per_page=10", {
      headers: {
        "Authorization": process.env.KYEW_CONN_MY_GITHUB_AUTH_HEADER,
        "User-Agent": "kyew-tool"
      }
    });
    const repos = await res.json();
    return Response.json({
      repos: repos.map(r => ({ name: r.full_name, stars: r.stargazers_count, language: r.language }))
    });
  }
}`,
    runtime: "javascript",
    allowed_domains: ["api.github.com"],
    connection_ids: ["my-github"]
  })

OAuth tokens are auto-refreshed before every execution. You don't need to handle token expiry in your code.

Using Connections in HTTP Proxy Tools

Reference a connection by name in http_config.connection_id:

tool(action="create",
  name="github_create_issue",
  tool_type="http_proxy",
  http_config={
    method: "POST",
    url_template: "https://api.github.com/repos/{{owner}}/{{repo}}/issues",
    body_template: { title: "{{title}}" },
    connection_id: "my-github"
  })

Managing Connections

List Connections

connection(action="list")

Update a Connection

connection(action="update", connection_id="my-github", name="github-personal")

Delete a Connection

connection(action="delete", connection_id="my-github")

Get Token (for debugging)

connection(action="get_token", connection_id="my-github")

Security Model

• Credentials are stored encrypted and scoped to your user account
• Environment variables are set via the sandbox SDK — no plaintext files in the container
• Each user's connections are fully isolated from other users
• Connections can be restricted to specific tools via allowed_tool_ids
• OAuth tokens are refreshed automatically, minimizing the window of token exposure

API Reference

For the full technical reference including all parameters and options, see connection Tool Reference. For a step-by-step walkthrough, see Connect a Service Guide.