Authentication

Authenticated Tailwind REST API endpoints use bearer authentication. For server-side integrations, include a Tailwind API key in the Authorization header. Public endpoints such as /health and /openapi.json do not require authentication.

Getting Your API Key

1. Log in to Tailwind
2. Navigate to Settings > API Access
3. Click Create API Key
4. Copy your key and store it securely

Full access or read only

When you create a key you choose its access:

• Full access (the default) can call every endpoint.
• Read only can call every endpoint that lists or reads data: accounts, boards, Pins, posts, schedules, analytics, feeds, keywords and usage. Any request that would change, publish, delete or spend something is refused with 403:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "reason": "insufficient_scope",
    "message": "This Tailwind API key is read-only, so it can't make changes. To allow this, create a full-access key in Tailwind Settings → Integrations and use it instead."
  }
}

A key’s access can’t be changed after it is created. To get full access, create a new key and revoke the read-only one. GET /v1/me returns the key’s scope: public:user for full access, public:read for read only.

Keep Your Key Secret

Your API key grants access to your Tailwind account. Never share it publicly or commit it to version control.

Using Your API Key

Include your API key in the Authorization header as a Bearer token:

curl -X GET https://api-v1.tailwind.ai/v1/accounts \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript Example

const response = await fetch('https://api-v1.tailwind.ai/v1/accounts', {
  headers: {
    'Authorization': `Bearer ${process.env.TAILWIND_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Tailwind API keys start with tw_pk_. OAuth access tokens issued by Tailwind are also accepted as bearer tokens; OAuth is primarily used by supported MCP clients.

Python Example

import requests
import os

response = requests.get(
    'https://api-v1.tailwind.ai/v1/accounts',
    headers={
        'Authorization': f'Bearer {os.environ["TAILWIND_API_KEY"]}',
        'Content-Type': 'application/json'
    }
)

data = response.json()

Environment Variables

We recommend storing your API key in environment variables:

# .env (add to .gitignore!)
TAILWIND_API_KEY=your_api_key_here

Error Responses

If authentication fails, you’ll receive a 401 Unauthorized response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  },
  "meta": {
    "requestId": "abc123"
  }
}

Common causes:

• Missing Authorization header
• Incorrect API key
• API key revoked in settings

API Key Permissions

API keys have full access to:

• All Pinterest accounts in your organization
• All boards and board lists
• Creating, scheduling, and deleting posts
• Viewing timeslots

Revoking API Keys

To revoke an API key:

1. Go to Settings > API Access
2. Find the key you want to revoke
3. Click Revoke

The key will be immediately invalidated and any requests using it will fail.