Authenticating against the Actuant API

The MCP endpoint accepts two kinds of bearer token. They are interchangeable at the transport level — same header, same endpoint, same tools. They differ in how you get one and how they are revoked.

API keys (act_…) — for scripts and CI

Mint one in Settings → Agents & MCP → Create API key. The plaintext is shown once at creation; only a SHA-256 hash is stored, so a lost key is regenerated, never recovered.

curl -X POST https://www.actuant.dev/api/mcp \
  -H "Authorization: Bearer act_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

OAuth (mca_…) — for agents

MCP-native clients do not need a key pasted in. They discover the authorization server, register themselves, and walk you through a browser sign-in. Actuant records which agent asked, which is what makes Settings → Agents & MCP able to list "Claude Code" rather than "a token".

The flow is standard and fully discoverable — RFC 8414 metadata, RFC 7591 dynamic client registration, authorization code with PKCE S256:

1. 1

   Discover

   GET /.well-known/oauth-authorization-server returns the issuer, endpoints, and supported methods.

2. 2

   Register

   POST /oauth/register with your client name and redirect URIs. No pre-shared secret; token_endpoint_auth_methods is "none".

3. 3

   Authorize

   Send the user to /oauth/authorize with a PKCE S256 challenge. They sign in and approve a consent screen naming your client.

4. 4

   Exchange

   POST /oauth/token with the code and verifier. Codes are single-use and expire in 10 minutes.

Issued tokens are mca_…, hashed at rest, and valid for 90 days. Revoking an agent in Settings kills its token immediately.

What a rejection looks like

An unauthenticated call returns 401 with a WWW-Authenticate header pointing at the resource metadata — this is what lets a compliant MCP client start the OAuth dance on its own:

HTTP/2 401
www-authenticate: Bearer error="invalid_token",
  error_description="No authorization provided",
  resource_metadata="https://www.actuant.dev/.well-known/oauth-protected-resource"