---
title: "Add external keys to access the intended services"
method: POST
path: "/workspaces/{workspace_id}/external_keys"
tags: ["External keys"]
---

# Add external keys to access the intended services

`POST /workspaces/{workspace_id}/external_keys`

## Request

- Base URL: `https://app.mammoth.io/api/v2`
- URL: `https://app.mammoth.io/api/v2/workspaces/{workspace_id}/external_keys`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-KEY` and API key in header `X-API-SECRET` and API key in header `X-WORKSPACE-ID`

External keys that lets Mammoth to user certain services. User brings their own key to access the service e.g AI based rules need an Open AI key

## Path parameters

- `workspace_id` integer, required: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.

## Request body

- AddExternalKeySpec: External key specification
  - `key_type` 'open_ai' | 'anthropic' | 'gemini' | 'grok', required: Type of the external key e.g. open_ai
  - `key_name` string, required: A name to be associated with the key
  - `description` string, nullable: Describe the purpose of the key and any added information related to it
  - `secure_key` string, required: The key value which will be used in the intended service
  - `model_id` string, nullable: The specific LLM model to use with this key e.g. claude-haiku-4-5. Defaults to the provider's recommended model if not specified.
  - `model_config` ModelConfigSpec
    - `thinking_budget` integer, nullable: Maximum thinking tokens (Anthropic/Gemini models). Use -1 for Gemini dynamic mode.
    - `thinking_level` string, nullable: Thinking level: minimal, low, medium, high (Gemini v3 models; minimal is Flash-only).
    - `reasoning_effort` string, nullable: Reasoning effort: low, high (Grok reasoning models).
    - `web_search` boolean, nullable: Enable live web search grounding (supported models only).
    - `cached_input` boolean, nullable: Enable prompt caching for repeated input prefixes to reduce cost (supported models only).

## Response `201`

Successful create

- ExternalKey
  - `id` integer, nullable: ID of the external key as saved in the DB
  - `key_type` 'open_ai' | 'anthropic' | 'gemini' | 'grok', nullable: Type of the external key e.g. open_ai
  - `key_name` string, nullable: A name to be associated with the key
  - `description` string, nullable: Describe the purpose of the key and any added information related to it
  - `secure_key` string, nullable: The key value which will be used in the intended service
  - `is_in_use` boolean, nullable: Is the key currently in use?
  - `model_id` string, nullable: The specific LLM model bound to this key e.g. claude-haiku-4-5
  - `model_config_data` ModelConfigSpec
    - `thinking_budget` integer, nullable: Maximum thinking tokens (Anthropic/Gemini models). Use -1 for Gemini dynamic mode.
    - `thinking_level` string, nullable: Thinking level: minimal, low, medium, high (Gemini v3 models; minimal is Flash-only).
    - `reasoning_effort` string, nullable: Reasoning effort: low, high (Grok reasoning models).
    - `web_search` boolean, nullable: Enable live web search grounding (supported models only).
    - `cached_input` boolean, nullable: Enable prompt caching for repeated input prefixes to reduce cost (supported models only).
  - `created_by_user_id` integer, nullable: ID of the user that created this key
  - `last_used_at` string, date-time, nullable: When was the key last used at?
  - `last_used_by_used_id` integer, nullable: ID of the user who the key in the recent most usage?
  - `created_at` string, date-time, nullable: When was the key created? Null for keys created before this was recorded.

## Other responses

- `400`: Bad Request
- `401`: Authorization error
- `403`: Request forbidden -- authorization will not help

---

[API](https://skmtc.dev/mammoth/apis/mammoth-analytics.md) · [All operations](https://skmtc.dev/mammoth/apis/mammoth-analytics/llms.txt) · [OpenAPI document](https://skmtc.dev/mammoth/apis/mammoth-analytics/revisions/4b2c943a00dc?raw)