> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kuudo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kuudo.com/_mcp/server.

# Exchange API key

POST https://app.kuudo.com/api/auth/token-exchange

Send the raw API key in Authorization: Bearer. No request body is needed. The resulting JWT lasts 300–900 seconds depending on client configuration (default 900). Keys must be active, unexpired and bound to an active local M2M client. Limited to 60 requests/minute independently per trusted client IP and valid API key. For delegated AI-agent connections, use [Agent Auth discovery](/api-reference/agent-auth/discover-agent-auth) and the [AI-agents guide](/guides/ai-agents); that protocol uses signed Agent Auth JWTs and does not exchange API keys.

Reference: https://docs.kuudo.com/api-reference/authentication/exchange-api-key

## Authentication

- `Authorization` header (bearer token, required) — Long-lived sk_live_* or sk_test_* key. Use for token exchange only.

## Response

### 200

Success

- `access_token` (string, required) — Short-lived JWT. Treat as a secret.
- `token_type` (enum, required)
  - Allowed values: `Bearer`
- `expires_in` (integer, required) — Seconds until expiry. Use this returned value rather than a fixed refresh interval.
- `scope` (string, required) — Space-separated granted scopes.
- `organization_id` (string, required)
- `client_id` (string, required)
- `plan` (string, required) — The organization's current plan. Current values are community, pro and scale. More may be added, so do not fail on an unrecognized value, and do not treat an unrecognized or missing value as entitled. It names the plan only; it does not say whether the account is in good standing.

## Errors

### 401 Unauthorized Error

Missing or invalid credentials, or inactive machine principal.

- `error` (ErrorError, required)
- `code` (string, optional)
- `details` (any, optional) — Endpoint-specific validation or failure details; shape varies.
- `requiredScopes` (list of string, optional)
- `errorCode` (string, optional)
- `message` (string, optional)
- `remediation` (string, optional)

### 403 Forbidden Error

Insufficient scope, authorization policy, or entitlement.

- `error` (ErrorError, required)
- `code` (string, optional)
- `details` (any, optional) — Endpoint-specific validation or failure details; shape varies.
- `requiredScopes` (list of string, optional)
- `errorCode` (string, optional)
- `message` (string, optional)
- `remediation` (string, optional)

### 429 Too Many Requests Error

Too many requests. Honor Retry-After where returned.

- `error` (ErrorError, required)
- `code` (string, optional)
- `details` (any, optional) — Endpoint-specific validation or failure details; shape varies.
- `requiredScopes` (list of string, optional)
- `errorCode` (string, optional)
- `message` (string, optional)
- `remediation` (string, optional)

### 500 Internal Server Error

Internal error.

- `error` (ErrorError, required)
- `code` (string, optional)
- `details` (any, optional) — Endpoint-specific validation or failure details; shape varies.
- `requiredScopes` (list of string, optional)
- `errorCode` (string, optional)
- `message` (string, optional)
- `remediation` (string, optional)

### 503 Service Unavailable Error

Dependency unavailable or application maintenance.

- `error` (ErrorError, required)
- `code` (string, optional)
- `details` (any, optional) — Endpoint-specific validation or failure details; shape varies.
- `requiredScopes` (list of string, optional)
- `errorCode` (string, optional)
- `message` (string, optional)
- `remediation` (string, optional)

## Types

### ErrorError

- string
- ErrorError1

### ErrorError1

- `code` (string, required)
- `message` (string, required)

## Examples

**Response**

```json
{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "servers:read",
  "organization_id": "org_example",
  "client_id": "m2m_example",
  "plan": "pro"
}
```

**SDK Code**

```python Authentication_exchangeApiKey_example
import requests

url = "https://app.kuudo.com/api/auth/token-exchange"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript Authentication_exchangeApiKey_example
const url = 'https://app.kuudo.com/api/auth/token-exchange';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Authentication_exchangeApiKey_example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.kuudo.com/api/auth/token-exchange"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Authentication_exchangeApiKey_example
require 'uri'
require 'net/http'

url = URI("https://app.kuudo.com/api/auth/token-exchange")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Authentication_exchangeApiKey_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://app.kuudo.com/api/auth/token-exchange")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Authentication_exchangeApiKey_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://app.kuudo.com/api/auth/token-exchange', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp Authentication_exchangeApiKey_example
using RestSharp;

var client = new RestClient("https://app.kuudo.com/api/auth/token-exchange");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Authentication_exchangeApiKey_example
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://app.kuudo.com/api/auth/token-exchange")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```