API Key Management

Create, view, and revoke API keys for authenticating with the Jinba Toolbox API

API keys authenticate requests to the Jinba Toolbox API. Every API call — whether executing a tool, managing ToolSets, or reading run history — requires a valid API key. Keys are scoped to an organization and grant access to that organization’s resources.

How API Keys Work

Authorization: Bearer jtb_xxxxxxxxxxxx

All API keys use the jtb_ prefix. When you create a key, the full key value is shown exactly once. After that, only a masked prefix is displayed in the console for identification purposes.

API keys are tied to the organization where they were created. A key for Organization A cannot access resources belonging to Organization B (except for executing public tools, which any valid key can do).

Creating an API Key

1. Navigate to API Keys

   Go to API Keys in the organization sidebar. You will see the list of existing keys (if any).

2. Click Create Key

   Click the Create API Key button at the top of the page. A modal will appear.

3. Enter a Name

   Give the key a descriptive name to identify its purpose (e.g. “Production Backend”, “CI/CD Pipeline”, “Local Development”). This name is for your reference only and does not affect the key’s permissions.

4. Copy the Key

   After clicking Create Key, the full API key is displayed. Copy it immediately and store it in a secure location.

   The full API key is shown only once at creation time. If you lose it, you must create a new key.

5. Done

   Click Done to close the modal. The new key will appear in the list with its name, masked prefix, creator, creation date, and last used date.

API Key List

The API Keys page displays a table with the following columns:

Column	Description
Name	The descriptive name you gave the key
Key Prefix	A masked preview of the key (e.g. jtb_abc1...) for identification
Created By	The user who created the key
Created	When the key was created
Last Used	The timestamp of the most recent API call made with this key

Revoking an API Key

To revoke a key, click the delete action next to the key in the list. A confirmation dialog will appear. Once revoked:

• The key is immediately invalidated.
• All API requests using this key will return a 401 Unauthorized error.
• The action is permanent and cannot be undone.

Revoking a key does not affect past run records or data. It only prevents future API calls using that key.

Authentication Scopes

API keys provide access based on the following scopes:

Read

List and retrieve ToolSets, tools, versions, runs, and other organization resources.

Write

Create, update, and delete ToolSets, tools, environment variables, and other resources.

Execute

Run tools and create run records. Required for both API execution and MCP tool calls.

Admin

Manage organization settings, members, and API keys. Full administrative access.

Using API Keys

REST API

Include the key in the Authorization header:

curl -X POST \
  https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/{slug}/tools/{toolSlug}/run \
  -H "Authorization: Bearer jtb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'

TypeScript SDK

Pass the key when creating the SDK client:

import { createClient } from "@jinba-toolbox/sdk";

const client = createClient({
  apiKey: process.env.JINBA_TR_API_KEY,
  organizationId: "your-org-id",
});

const result = await client.run("slack-tools", "post-message", {
  channel: "#general",
  text: "Hello from Jinba Toolbox!",
});

MCP Endpoint

When connecting an AI agent to a ToolSet’s MCP endpoint, provide the API key as part of the connection configuration. The MCP endpoint URL is available in the ToolSet detail page when MCP Server is enabled.

Personal vs. Organization API Keys

Jinba Toolbox supports two levels of API keys:

Type	Scope	Location
Organization API Key	Scoped to a single organization’s resources	Organization sidebar > API Keys
Personal API Key	Scoped to the user’s account	Dashboard > API Keys

Organization API keys are recommended for most use cases. They are easier to manage, rotate, and revoke without affecting individual user accounts.

Best Practices

• Use descriptive names — Name keys by their purpose and environment (e.g. “Production API Server”, “Staging CI”) so you can identify which key to revoke if needed.
• Rotate keys regularly — Create new keys and revoke old ones periodically to limit the impact of a potential leak.
• Never commit keys to source control — Store keys in environment variables or a secrets manager.
• Use separate keys per environment — Create distinct keys for development, staging, and production.
• Revoke unused keys — If a key is no longer needed, revoke it immediately. Check the “Last Used” column to identify dormant keys.
• Prefer organization keys — Use organization-scoped keys rather than personal keys for application integrations.