Bring Your Own X Keys

How do I use my own X API keys with Chirpie?

Create an app in the X Developer Portal, register https://chirpie.ai/api/auth/x/callback as its callback URI, then give Chirpie the app's OAuth 2.0 client ID and secret (dashboard, CLI, SDK, or API). Reconnect each X account you want to move onto your app. Those accounts then post against your X API allowance instead of Chirpie's, and Chirpie's X link-post surcharge does not apply to them.

The five steps below cover it end to end. It takes about ten minutes.

Why you might want this

X charges API operators per post. By default, your X accounts connect through Chirpie's X developer app and post against Chirpie's X API allowance, which is what Chirpie's X link-post surcharge pays for. Register your own X app and those posts bill your X developer account directly instead — so the surcharge is waived on every account connected that way.

1. Create an X app

1. Go to the X Developer Portal and sign in with the X account that will own the app.
2. Create a project, then an app inside it. Any name works — X requires it to be globally unique.
3. Open the app's User authentication settings and click Set up.

2. Configure the app

Required scopes

Chirpie requests these OAuth 2.0 scopes:

tweet.read tweet.write users.read offline.access

Media uploads additionally use media.write. offline.access is what lets Chirpie refresh your tokens in the background — without it, connections expire within hours.

3. Copy your credentials

After saving, X shows an OAuth 2.0 Client ID and Client Secret. Copy the secret now — X only displays it once. If you lose it, regenerate it in the app's Keys and tokens tab and update Chirpie.

4. Add the keys to Chirpie

# Omit --client-secret to be prompted without echoing it to the terminal
chirpie accounts x-keys set --client-id "YOUR_CLIENT_ID" --label "Acme social app"

chirpie accounts x-keys status
chirpie accounts x-keys remove

import { ChirpieClient } from "@chirpie/sdk";

const chirpie = new ChirpieClient({ apiKey: process.env.CHIRPIE_API_KEY! });

await chirpie.setXKeys({
  client_id: process.env.X_CLIENT_ID!,
  client_secret: process.env.X_CLIENT_SECRET!,
  label: "Acme social app",
});

const status = await chirpie.getXKeysStatus();
// { configured: true, client_id_last4: "3456", redirect_uri: "...", ... }

await chirpie.removeXKeys();

curl -X PUT https://chirpie.ai/api/v1/accounts/x/keys \
  -H "Authorization: Bearer $CHIRPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "label": "Acme social app"
  }'

5. Reconnect your X account

Adding keys does not move accounts that are already connected. Reconnect each X account you want on your app:

chirpie accounts connect-x

Accounts using your app report "byo_keys": true in GET /api/v1/accounts. Accounts you don't reconnect keep working exactly as before, through Chirpie's app.

Which X plan do you need?

X's Free API tier allows a small number of posts per month and is enough to try this out. Sustained posting needs X's Basic tier or higher. Check X's current API pricing — the tiers and limits are set by X and change from time to time.

If X rate-limits or rejects a post, the error surfaces on the post as-is, so you can tell an X quota problem apart from a Chirpie one.

Removing your keys

Removing your keys stops token refresh for every X account connected through your app — those accounts stop publishing until you either re-add the keys or reconnect them through Chirpie's app.

chirpie accounts x-keys remove

Security

• Your client ID and secret are encrypted at rest with AES-256-GCM.
• The secret is never returned by any endpoint, logged, or shown again in the dashboard. Status responses include only the last four characters of the client ID.
• Keys are scoped to your account. Only your API keys and your dashboard session can read or change them.
• Revoking the app in X's developer portal immediately cuts off access, whatever Chirpie has stored.

FAQ

Does this change my Chirpie bill?

Only the X link-post surcharge. Posts from accounts connected through your own X app are exempt from it. Everything else — your plan price, your monthly post allowance, per-post overage — is unchanged, and posts still count toward your plan's post limit.

Can I post links to X on the Free plan with my own keys?

Yes. Link posts to X are not available on the Free plan through Chirpie's app, because X charges per link post. An X account connected through your own app pays X directly, so the restriction does not apply to it — link posts from that account go out on any plan, billed to you by X.

Do I have to move all my X accounts?

No. The setting applies per account, decided at connect time. Reconnect only the accounts you want on your app; the rest keep using Chirpie's app. Accounts using your app return "byo_keys": true from GET /api/v1/accounts and show a Your X app tag in the dashboard.

What happens to my already-connected accounts?

Nothing. Adding keys never moves an account on its own — reconnecting is what switches an account onto your app, and reconnecting after removing your keys switches it back to Chirpie's.

Does this work for platforms other than X?

Not today. Bring-your-own developer keys are X-only. Every other platform connects through Chirpie's apps as usual.

Can Chirpie or anyone else read my client secret?

No endpoint returns it, and it is never written to logs or redisplayed in the dashboard. It is encrypted at rest with AES-256-GCM, and status responses show only the last four characters of the client ID so you can confirm which app is stored. If you lose the secret, regenerate it in X's portal and save the new one.

Can I change my keys later?

Yes. Saving new values replaces the stored pair. Reconnect each X account afterwards so it authorizes against the new app.

Does the OAuth flow still go through chirpie.ai?

Yes — only the app identity changes. That is why your app must register https://chirpie.ai/api/auth/x/callback exactly.

Troubleshooting