Twitter / X Setup Guide

Enables your agent to post tweets, read timelines, send DMs, like, retweet, search, and manage bookmarks on Twitter/X.

Overview

Twitter uses two authentication layers. The Bearer Token provides app-level read-only access (search, read timelines). OAuth 1.0a user tokens (access_token + access_token_secret) are required for any write action — posting tweets, sending DMs, liking, retweeting. Most users will want both.

Prerequisites

• A Twitter/X account
• A Twitter Developer account at developer.twitter.com
• A Developer App with Read and Write permissions enabled

Step 1: Create a Developer App

1. Go to the Twitter Developer Portal
2. Create a Project (if you don't have one)
3. Inside the project, create an App
4. Note the App name — you'll need it for the settings below

Step 2: Set App Permissions to Read and Write

This is the most commonly missed step. The default permission is Read Only.

1. In the Developer Portal, go to your App's Settings tab
2. Scroll to User authentication settings and click Set up
3. Under App permissions, select Read and write
4. Under Type of App, select Web App, Automated App or Bot
5. Set a Callback URL — use https://localhost (not used for BYOK, but required by Twitter)
6. Set a Website URL — any valid URL
7. Click Save

Step 3: Enable OAuth 1.0a

OAuth 1.0a and OAuth 2.0 are separate toggles in the Developer Portal. Even if OAuth 2.0 is enabled, you must also enable OAuth 1.0a for the access token/secret to work.

1. In your App settings, ensure OAuth 1.0a is turned on under User authentication settings
2. This should already be done if you completed Step 2, but verify the toggle is active

Step 4: Generate Credentials

1. Go to your App's Keys and Tokens tab
2. Under Consumer Keys:
   • Copy the API Key → this is your api_key
   • Copy the API Key Secret → this is your api_secret
3. Under Authentication Tokens > Bearer Token:
   • Click Generate (or Regenerate)
   • Copy the token (starts with AAAA) → this is your bearer_token
4. Under Authentication Tokens > Access Token and Secret:
   • Click Generate (or Regenerate)
   • Ensure it says Created with Read and Write permissions — if it says Read Only, go back to Step 2
   • Copy the Access Token → this is your access_token
   • Copy the Access Token Secret → this is your access_token_secret

Step 5: Connect in Carapace

1. Go to Dashboard > Connections
2. Find Twitter / X and click Connect
3. Fill in the fields:
   • API Key — Consumer Key from Step 4
   • API Secret — Consumer Secret from Step 4
   • Bearer Token — starts with AAAA
   • Access Token — (optional but required for posting)
   • Access Token Secret — (optional but required for posting)
4. Click Save Credentials

Credential Fields Reference

Gotchas

Read-only without access tokens: If you only provide api_key, api_secret, and bearer_token, the agent can read timelines and search but cannot post tweets, send DMs, or perform any write action. The access_token and access_token_secret are what enable posting.

OAuth 1.0a must be explicitly enabled: Twitter's Developer Portal has separate toggles for OAuth 1.0a and OAuth 2.0. Enabling one does not enable the other. The Carapace integration uses OAuth 1.0a user context tokens for write operations.

Permissions are baked into the access token: If you generated access tokens while the app was set to Read Only, those tokens are permanently read-only. You must regenerate them after changing permissions to Read and Write. Look for the label "Created with Read and Write permissions" when generating.

"API Key" naming confusion: Twitter's UI uses inconsistent labels. "API Key" and "Consumer Key" are the same thing. "API Key Secret" and "Consumer Secret" are the same thing. The Carapace dashboard field is labeled api_key.

Rate limits on free tier: Twitter's free API tier (Basic) has aggressive rate limits — 1,500 tweets per month, 50 requests per 15 minutes on most endpoints. Heavy agent usage may require the Pro or Enterprise tier.

Troubleshooting

Agent can read but can't post tweets

Your access tokens were likely generated with Read Only permissions. Go to App Settings > User authentication settings, verify Read and write is selected, then go back to Keys and Tokens and regenerate the Access Token and Secret.

401 Unauthorized on all requests

Your Consumer Key/Secret pair is invalid or the app has been suspended. Regenerate all keys from the Developer Portal.

403 Forbidden on tweet creation

Your app permissions are Read Only. Follow Step 2 to change to Read and Write, then regenerate access tokens.

See Also

• Twitter OAuth 1.0a docs
• Twitter API rate limits
• Developer Portal