Authentication

OAuth 2.0 Client Credentials and API keys

Authenticate programmatically using OAuth 2.0 Client Credentials or the legacy API key exchange. Both return a runtime token (JWT) valid for 60 minutes. Use the token as Authorization: Bearer <token> for MCP Farm requests and other authenticated Pinkfish API calls.

This runtime token is the bearer credential for the MCP Farm. The same token also authenticates other Pinkfish API calls — for example PinkConnect connection management (see Connecting to MCPs).

Create API Credentials

1. Settings → API Credentials → Create Credential
2. Copy the Client ID and Client Secret immediately (the secret is shown once)
3. Note your Organization ID (shown on the same page)

New credentials may take up to 60 seconds to activate.

OAuth 2.0 Client Credentials (Recommended)

Exchange your Client ID and Client Secret for an access token using the standard OAuth 2.0 Client Credentials grant (RFC 6749 Section 4.4).

curl -X POST "https://app-api.app.pinkfish.ai/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=org:YOUR_ORG_ID"

You can also send credentials via the Authorization: Basic header:

curl -X POST "https://app-api.app.pinkfish.ai/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
  -d "grant_type=client_credentials" \
  -d "scope=org:YOUR_ORG_ID"

Parameter	Required	Description
grant_type	Yes	Must be client_credentials
client_id	Yes	Your credential’s Client ID
client_secret	Yes	Your credential’s Client Secret
scope	Yes	org:<organization_id>

Response:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Error Response:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Legacy API Key Exchange

The original token exchange endpoint is still available for backward compatibility.

curl -s -X POST "https://app-api.app.pinkfish.ai/auth/token" \
  -H "X-Api-Key: YOUR_CLIENT_SECRET" \
  -H "X-Selected-Org: YOUR_ORG_ID" \
  -H "Content-Type: application/json"

Header	Required	Description
X-Api-Key	Yes	Your Client Secret (the pf_live_... value)
X-Selected-Org	Yes	Organization ID
Content-Type	Yes	application/json

Response: { "token": "eyJhbGciOi..." }

Example Call to Weather MCP

Use the token to call an MCP server. Here’s an example calling the Weather service to get a forecast:

curl -X POST "https://mcp.app.pinkfish.ai/weather" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $PINKFISH_TOKEN" \
  -H "X-Selected-Org: $ORG_ID" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"weather_get_current","arguments":{"city":"London"}}}'

Bootstrap Script

Get token and export it. Requires curl and jq.

#!/bin/bash
CLIENT_ID="<YOUR_CLIENT_ID>"
CLIENT_SECRET="<YOUR_CLIENT_SECRET>"
ORG_ID="<YOUR_ORG_ID>"

R=$(curl -s -X POST "https://app-api.app.pinkfish.ai/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=org:${ORG_ID}")
export PINKFISH_TOKEN=$(echo "$R" | jq -r '.access_token')
[ "$PINKFISH_TOKEN" = "null" ] || [ -z "$PINKFISH_TOKEN" ] && { echo "Auth failed"; echo "$R" | jq .; exit 1; }