---
title: "Exchange an API key for an external agent token"
method: POST
path: "/agentTokens"
tags: ["AgentToken"]
---

# Exchange an API key for an external agent token

`POST /agentTokens`

## Request

- Base URL: `https://api.mabl.com`
- URL: `https://api.mabl.com/agentTokens`
- Auth: one of:
  - HTTP basic
  - API key in header `Authorization`

Exchanges a workspace API key, sent with Basic authentication, for a short-lived external_agent access token for a coding agent the key connected. The token acts for the key: it reaches only the key's workspace, with the key's scopes within the external_agent ceiling, and stops working when the key is disabled, expired or deleted. Nothing is stored; exchange again before the token expires. Agent tokens, people's tokens, and login, impersonation, invitation, agent-bound, company and global keys are refused.

## Request body

- CreateAgentTokenRequest
  - `client_kind` 'mcp' | 'cli', required: Which kind of client an external agent (a coding agent a person or API key connected) acts through

## Response `201`

The external agent access token.

- AgentToken
  - `access_token` string, required: An external_agent access token acting for the API key.
  - `token_type` string, required: Always Bearer.
  - `expires_in` integer, required: Seconds until the access token expires, at most 900 and never past the API key's expiry.

## Other responses

- `401`: The credential is not valid or is not an exchangeable workspace API key.
- `default`: Unknown error

## Changes

- **2026-10-19** `b602223aa51f`: 2 info
  - added the optional property `guardrail/allOf[#/components/schemas/GuardrailRefusal]/approval` to the response with the `401` status
  - added the optional property `guardrail/allOf[#/components/schemas/GuardrailRefusal]/approval` to the response with the `default` status
- **2026-10-17** `91ff383fb7f9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mabl/apis/mabl-api/changes/agentTokens/post.md)

---

[API](https://skmtc.dev/mabl/apis/mabl-api.md) · [All operations](https://skmtc.dev/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mabl/apis/mabl-api/revisions/b602223aa51f?raw)