> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Navigate to API Keys">
    Go to **API Keys** in the organization sidebar. You will see the list of existing keys (if any).
  </Step>

  <Step title="Click Create Key">
    Click the **Create API Key** button at the top of the page. A modal will appear.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Copy the Key">
    After clicking **Create Key**, the full API key is displayed. Copy it immediately and store it in a secure location.

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

  <Step title="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.
  </Step>
</Steps>

## 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.

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

## Authentication Scopes

API keys provide access based on the following scopes:

<CardGroup cols={2}>
  <Card title="Read" icon="eye">
    List and retrieve ToolSets, tools, versions, runs, and other organization resources.
  </Card>

  <Card title="Write" icon="pen">
    Create, update, and delete ToolSets, tools, environment variables, and other resources.
  </Card>

  <Card title="Execute" icon="play">
    Run tools and create run records. Required for both API execution and MCP tool calls.
  </Card>

  <Card title="Admin" icon="shield-halved">
    Manage organization settings, members, and API keys. Full administrative access.
  </Card>
</CardGroup>

## Using API Keys

### REST API

Include the key in the `Authorization` header:

```bash theme={null}
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:

```typescript theme={null}
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            |

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

## 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.