> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure sua própria API Key do X
> Guia passo a passo para conectar suas próprias credenciais de API do X (Twitter) ao Ayrshare
Em 31 de março de 2026, o X alterou a forma como plataformas de terceiros acessam sua API. Como resultado, toda conta do Ayrshare que publica no X pelo Ayrshare precisa registrar seu próprio X Developer App e usar sua API Key e API Secret em cada requisição.
Essa é uma mudança determinada pelo X para toda a plataforma e afeta todas as ferramentas de terceiros.
**As chaves BYO são definidas uma vez por plataforma (para toda a conta), não por cliente ou sub-profile.** Você cria **um X Developer App** sob sua própria conta do X, e a mesma **API Key + API Secret** se aplicam a toda a conta para o X — elas são usadas em **todos** os sub-profiles / usuários finais que vinculam o X sob sua conta do Ayrshare. Se você tiver um Business ou Enterprise Plan com centenas de sub-profiles, você **não** precisa repetir esta configuração para cada um. Você configura uma vez para a plataforma do X e, em seguida, passa os mesmos dois headers em cada requisição.
Simplificamos o processo de configuração para torná-lo o mais simples possível, e deve levar menos de 10 minutos para concluir. Siga nosso guia passo a passo abaixo e, se precisar de ajuda no caminho, nossa equipe está disponível para auxiliar.
## Etapa 1: Crie sua conta de desenvolvedor no X
Acesse [console.x.com](https://console.x.com) e entre com sua conta do X. Consulte o [guia de introdução do X](https://docs.x.com/x-api/getting-started/getting-access) se precisar de ajuda.
Conclua o onboarding de desenvolvedor e aceite o Developer Agreement e as políticas.
Você agora está no X Developer Console.
## Etapa 2: Crie um app
Você cria apenas **um X Developer App por conta do Ayrshare**. O mesmo app e sua API Key + API Secret são reutilizados para cada sub-profile / usuário final que você vincular posteriormente sob sua conta do Ayrshare. Você não cria um novo app por cliente.
No Developer Console, navegue até **Apps**.
No painel de Apps, clique em **Create App** (consulte a [documentação de configuração do App do X](https://docs.x.com/fundamentals/developer-apps) para detalhes). Insira um nome de app (normalmente o nome da sua marca). Esse nome aparecerá na tela de autorização OAuth quando os usuários conectarem sua conta do X.
Selecione o ambiente **Production** no menu suspenso.
O X gerará várias credenciais. **Ignore essas credenciais e feche esta janela.**
## Etapa 3: Configure as permissões do app
Em "Apps", localize o novo app (atualize a página se ele não aparecer) e, em seguida, clique nele para ver os detalhes.
Em **User authentication settings**, clique em **Set up**.
Em **App permissions**, selecione **Read and write and Direct message**. Isso é necessário para suporte completo aos recursos, incluindo publicação e DMs.
Em **Type of App**, selecione **Web App, Automated App or Bot**. Essa é a escolha correta para integrações do lado do servidor como a do Ayrshare.
Em **App info**:
* **Callback URL:** adicione as duas URLs de callback a seguir:
* `https://profile.ayrshare.com/social-accounts`
* `https://app.ayrshare.com/social-accounts`
* **Website URL:** `https://app.ayrshare.com`
**Não pule esta etapa.** Essas callback URLs são obrigatórias para o fluxo de vinculação OAuth. Quando seus usuários finais autorizam a conexão do X, o X os redireciona de volta para uma dessas URLs para concluir o processo de vinculação. Se elas estiverem ausentes, o fluxo OAuth falhará com um erro `403 Callback URL not approved`.
Clique em **Save**. Você pode ignorar o pop-up de OAuth 2.0, pois usará apenas 2 das chaves de OAuth 1.0 (API Key e API Secret).
**Importante: defina as permissões antes de vincular.** As permissões que você escolhe aqui determinam o que seu app pode fazer. Se você alterar as permissões após vincular sua conta do X via OAuth, precisará vincular novamente para que o novo Access Token herde as permissões atualizadas.
Certifique-se de armazenar estas 2 chaves:
1. **API Key** (também chamada de Consumer Key, o identificador do app do X)
2. **API Secret** (também chamada de Consumer Secret)
Você **NÃO** precisa gerar Access Tokens manualmente. O Ayrshare cuida disso automaticamente quando você vincula sua conta do X via OAuth.
## Etapa 4: Compre créditos da API do X
O X agora usa cobrança baseada em créditos para a API, comprados pelo Developer Console.
No Developer Console, clique em **Billing → Credits** na barra lateral esquerda.
Compre créditos (o mínimo é \$5, o que é suficiente para centenas de chamadas de API). Cada chamada de API custa uma fração de centavo, então o custo deve ser mínimo para a maioria dos usuários.
Você pode habilitar a **auto-recharge** para evitar interrupções de serviço e gerenciar seu limite de gastos definindo um valor máximo que pode gastar em seu ciclo de faturamento.
**Suas chamadas de API falharão sem créditos.** A API do X é paga por uso. Se seu saldo de créditos estiver zerado, cada requisição de API retornará um erro `402 CreditsDepleted` com a mensagem "Your enrolled account does not have any credits to fulfill this request.". Isso inclui publicação, leitura de tweets e buscas de usuários. Carregue créditos antes de testar sua integração. Consulte [Como funciona a precificação da API do X](#how-x-api-pricing-works) para uma atualização completa sobre a precificação do X.
## Etapa 5: Atualize suas chamadas de API do Ayrshare
Na Etapa 3, você salvou esses 2 itens com segurança em seu próprio env, config ou gerenciador de segredos:
1. **API Key** (também chamada de Consumer Key, o identificador do app do X)
2. **API Secret** (também chamada de Consumer Secret)
Agora, adicione suas credenciais do X aos headers das suas chamadas de API do Ayrshare.
**Suas chaves permanecem privadas.** Sua API Key e API Secret não são armazenadas pelo Ayrshare.
### Referência de headers
| Header | Valor |
| ----------------------------- | -------------------------------- |
| `X-Twitter-OAuth1-Api-Key` | API Key (Consumer Key) |
| `X-Twitter-OAuth1-Api-Secret` | API Key Secret (Consumer Secret) |
**Como saber se suas permissões estão erradas:**
* Se as permissões do seu app estiverem mal configuradas, sua requisição de API pode retornar um erro `403 Forbidden` com a mensagem: "Your client app is not configured with the appropriate OAuth1 app permissions.".
Se você vir esse erro, atualize as permissões do app para **Read and write and Direct message** no X Developer Console e, em seguida, vincule novamente sua conta do X via OAuth para que o novo Access Token herde as permissões atualizadas.
### Exemplos de código
```bash cURL theme={"system"}
curl -X POST https://api.ayrshare.com/api/post \
-H "Authorization: Bearer YOUR_AYRSHARE_API_KEY" \
-H "X-Twitter-OAuth1-Api-Key: your_api_key" \
-H "X-Twitter-OAuth1-Api-Secret: your_api_secret" \
-H "Content-Type: application/json" \
-d '{"post": "Hello from my own X App!", "platforms": ["twitter"]}'
```
```javascript Node.js theme={"system"}
const response = await fetch("https://api.ayrshare.com/api/post", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_AYRSHARE_API_KEY",
"Content-Type": "application/json",
"X-Twitter-OAuth1-Api-Key": process.env.X_API_KEY,
"X-Twitter-OAuth1-Api-Secret": process.env.X_API_SECRET,
},
body: JSON.stringify({
post: "Hello from my own X App!",
platforms: ["twitter"],
}),
});
```
```python Python theme={"system"}
import os
import requests
headers = {
"Authorization": "Bearer YOUR_AYRSHARE_API_KEY",
"Content-Type": "application/json",
"X-Twitter-OAuth1-Api-Key": os.environ["X_API_KEY"],
"X-Twitter-OAuth1-Api-Secret": os.environ["X_API_SECRET"],
}
response = requests.post(
"https://api.ayrshare.com/api/post",
headers=headers,
json={"post": "Hello from my own X App!", "platforms": ["twitter"]},
)
```
Suas automações e fluxos de trabalho existentes continuarão funcionando desde que você inclua os headers de API Key e API Secret em cada requisição que aponta para o X.
### Migrando profiles existentes (Business & Enterprise)
Se você tem sub-profiles que já estão vinculados ao X pelo Ayrshare, esses profiles precisarão revincular suas contas do X depois que você migrar para as chaves BYO. Isso ocorre porque os access tokens existentes foram emitidos sob o app do X do Ayrshare e não podem ser usados com suas consumer keys (assinaturas OAuth 1.0a estão vinculadas ao app que emitiu o token).
Adicione `twitterApiKey` e `twitterApiSecret` ao corpo da sua chamada [generateJWT](/apis/profiles/generate-jwt#body-parameters-13). Eles são criptografados antes de serem incorporados ao JWT e não ficam expostos para seus usuários finais.
```json theme={"system"}
{
"domain": "your-domain",
"profileKey": "...",
"privateKey": "...",
"twitterApiKey": "YOUR_X_CONSUMER_KEY",
"twitterApiSecret": "YOUR_X_CONSUMER_SECRET"
}
```
Esta é a única requisição em que suas consumer keys vão no corpo. Todas as outras requisições do X usam os headers descritos acima.
Depois de gerar o JWT com as chaves incluídas, seus usuários precisam reconectar sua conta do X pela página de vinculação do profile. A tela de consentimento OAuth agora mostrará o nome do seu app em vez do Ayrshare.
Para simplificar isso, você pode:
* Desvincular contas programaticamente pela [Unlink API](/apis/profiles/unlink-social-network#unlink-a-social-network) e, em seguida, pedir aos usuários para reautorizar
* Usar o [parâmetro `logout`](/apis/profiles/generate-jwt#param-logout) em generateJWT para forçar um login novo
* Usar [`allowedSocial`](/apis/profiles/generate-jwt#param-allowed-social) para mostrar apenas o X na página de vinculação durante o fluxo de migração
Após revincular, continue incluindo os headers `X-Twitter-OAuth1-Api-Key` e `X-Twitter-OAuth1-Api-Secret` em cada chamada de API (publicação, análises, comentários etc.).
Uma vez que um profile foi revinculado sob seu app do X, todas as publicações subsequentes para esse profile usarão suas credenciais. Você pode verificar isso conferindo a página Usage no seu [X Developer Console](https://console.x.com).
### Verifique sua configuração
Faça uma chamada de teste pela API do Ayrshare com seus novos headers para confirmar que tudo está funcionando. O endpoint [/analytics/social](/apis/analytics/social) é um bom teste leve, já que não cria publicações.
## Como funciona a precificação da API do X
Anteriormente, o Ayrshare cobria o custo do uso da API do X em seu nome. Sob o modelo atual do X, cada cliente do Ayrshare mantém sua própria conta de desenvolvedor no X e paga diretamente ao X pelas requisições de API que sua aplicação faz. (Uma conta de desenvolvedor do X por conta do Ayrshare, não por usuário final. Todos os seus sub-profiles compartilham a mesma conta de desenvolvedor do X e o mesmo saldo de créditos.)
O modelo de precificação do X é paga-por-uso: você compra créditos no X Developer Console, e eles são debitados conforme as requisições de API são feitas. Não são necessários contratos ou assinaturas.
Operações típicas são baratas. Por exemplo:
| Operação | Custo aproximado |
| ------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Criar uma publicação (apenas texto) | \~\$0,01 por publicação |
| Criar uma publicação com mídia | \~\$0,02 por publicação (upload de mídia e criação da publicação são requisições separadas) |
| Ler uma publicação | \~\$0,005 por leitura |
| Busca de usuário | \~\$0,01 por busca |
| Enviar uma DM | \~\$0,01 por mensagem |
| Ler eventos de DM | \~\$0,01 por evento |
| Interações do usuário (seguir, curtir etc.) | \~\$0,015 por requisição |
Para contexto, se você publica cerca de 100 vezes por mês, seu custo direto no X seria em torno de \$1, e publicações com mídia seriam aproximadamente \$2 por mês.
A precificação paga-por-uso do X está atualmente em fase piloto. As tarifas estão sujeitas a alterações, e custos adicionais podem ser introduzidos. Sempre consulte o Developer Console para a precificação mais atual. Consulte o [detalhamento das informações de preços do X](https://docs.x.com/x-api/fundamentals/pricing).
Sabemos que isso introduz um custo que não existia antes, e queremos ser transparentes quanto a isso. Ao mesmo tempo, esse modelo também desbloqueia diversos benefícios que não eram possíveis no antigo modelo de chave compartilhada.
## Benefícios de usar sua própria API Key do X
Usar suas próprias credenciais de API do X oferece mais controle e confiabilidade do que o modelo anterior de chave compartilhada. Isso inclui:
* **Experiência OAuth com sua marca:** os usuários veem o nome do seu app e sua marca ao autorizar o acesso ao X.
* **Limites de taxa dedicados:** seu uso da API é regido pelos limites da sua própria conta de desenvolvedor do X, separada de outros usuários do Ayrshare. Você pode monitorar seu uso no [X Developer Console](https://console.x.com) e revisar a [documentação de rate limits da API do X](https://developer.x.com/en/docs/x-api/rate-limits).
* **Controle de credenciais:** sua API Key e Secret permanecem em sua própria conta de desenvolvedor do X. O Ayrshare não armazena suas chaves secretas.
* **Portabilidade:** como os usuários se autenticam com seu X App, sua integração permanece totalmente sob seu controle.
* **Visibilidade de uso:** seu painel de desenvolvedor do X mostra requisições de API, limites de taxa e uso de créditos.
O X é a primeira plataforma a exigir esse modelo, mas mais plataformas estão migrando para "traga sua própria API key". Estamos expandindo essa capacidade em todo o Ayrshare, para que os desenvolvedores tenham o mesmo controle e independência em todas as plataformas sociais.
## Segurança
* Sua API Key e API Secret não são armazenadas pelo Ayrshare.
* Para boas práticas gerais de segurança, consulte o [guia de segurança de autenticação do X](https://docs.x.com/resources/fundamentals/authentication).
## FAQ
**Não.** Você configura **um** X Developer App sob sua própria conta do X, e a mesma **API Key + API Secret** são reutilizadas para cada sub-profile / usuário final que você vincular sob sua conta do Ayrshare.
* Você cria o X Developer App **uma vez**.
* Você passa os mesmos dois headers (`X-Twitter-OAuth1-Api-Key` e `X-Twitter-OAuth1-Api-Secret`) em cada chamada de API do Ayrshare, independentemente do sub-profile a que a chamada se refere.
* Seus usuários finais ainda passam pelo fluxo de vinculação OAuth para autorizar sua própria conta do X, mas eles **não** precisam do próprio X Developer App ou API keys. Eles se conectam por meio do seu app.
* Todos os sub-profiles compartilham a mesma conta de desenvolvedor do X, os mesmos rate limits e o mesmo saldo de créditos.
A única vez em que você lida com as chaves por profile é no corpo do [generateJWT](/apis/profiles/generate-jwt) durante a migração, o que ainda é o mesmo par de chaves suas, apenas entregue à página de vinculação para que os usuários finais possam reautorizar sob seu app.
Sim. A partir de 31 de março de 2026, todas as operações do X pelo Ayrshare exigem suas próprias credenciais de API do X. Se você ainda não configurou sua conta de desenvolvedor do X, siga as etapas acima.
Publicar no X pelo Ayrshare exige suas próprias credenciais de API do X. Requisições sem credenciais BYO válidas são rejeitadas. Publicar em outras plataformas (Instagram, LinkedIn, Facebook, TikTok etc.) não é afetado.
O X cobra por chamada de API. Criar uma publicação custa cerca de \$0,01, e ler uma publicação custa cerca de \$0,005. Por exemplo, publicar 100 vezes por mês custaria aproximadamente \$1. Consulte a [página de preços do X](https://docs.x.com/x-api/fundamentals/pricing) para todos os detalhes.
Não. O preço da sua assinatura do Ayrshare continua o mesmo. O único custo adicional é a taxa de uso da API do X faturada diretamente pelo X pela sua conta de desenvolvedor.
Não. Sua API Key e API Secret não são armazenadas pelo Ayrshare. Para boas práticas gerais de segurança, consulte o [guia de segurança de autenticação do X](https://docs.x.com/resources/fundamentals/authentication).
Sim. Você pode usar seu X App existente desde que ele tenha as permissões "Read and write" habilitadas (e Direct Messages se você usa recursos de DM).
Você precisará da sua API Key (Consumer Key) e API Secret (Consumer Secret) da seção Keys and tokens do X Developer Console. Vincule sua conta do X via OAuth e, em seguida, inclua esses 2 headers nas suas requisições de API do Ayrshare.
Se você alterou as permissões do app depois da configuração inicial, revincule sua conta do X para que o Access Token herde as permissões atualizadas.
Você precisa da sua API Key (Consumer Key) e API Secret (Consumer Secret). Consulte a [tabela de referência de headers](#header-reference) acima para saber exatamente qual header do Ayrshare cada uma mapeia. Você pode ignorar o Client ID, Client Secret, Bearer Token, Access Token e Access Token Secret.
São credenciais totalmente diferentes para métodos de autenticação diferentes:
* **API Key** (também chamada de "Consumer Key") é para OAuth 1.0a. API Key (Consumer Key) + API Secret é o que o Ayrshare usa. Funciona com todos os recursos do X, os tokens nunca expiram e nenhuma lógica de refresh é necessária.
* **Client ID** é para OAuth 2.0. Você NÃO precisa disso para o Ayrshare. Os tokens de OAuth 2.0 expiram após um curto período e exigem gerenciamento de refresh token.
Para o Ayrshare, você só precisa da sua API Key e API Secret. Você pode ignorar o Client ID, Client Secret e Bearer Token.
Os access tokens do OAuth 2.0 expiram a cada 2 horas, e os refresh tokens do X são de uso único (cada refresh invalida o token antigo). Isso torna impossível suportar um modelo BYO sem estado, especialmente para publicações agendadas. Os tokens OAuth 1.0a nunca expiram, funcionam com todos os recursos do X e não exigem nenhum gerenciamento de tokens.
Sim. Se seus usuários vincularam o X pelo Ayrshare antes de você configurar as chaves BYO, eles precisarão reconectar. Os access tokens existentes foram emitidos sob o app do X do Ayrshare e não funcionarão com suas consumer keys. Consulte [Migrando profiles existentes](#migrating-existing-profiles-business--enterprise) acima para o processo passo a passo.
Não. Essa mudança afeta apenas a publicação no X. Todas as outras integrações de plataforma no Ayrshare continuam funcionando normalmente.
A publicação automática por RSS no X não é mais suportada. Feeds RSS são executados automaticamente em um cronograma, mas o modelo de "traga sua própria API key" exige que as credenciais sejam fornecidas em cada requisição de API. Por isso, os feeds RSS não conseguem se autenticar quando a publicação é enviada.
Se você usava RSS para publicar no X, recomendamos migrar para [publicações agendadas](/apis/post/overview#schedule-posts) ou chamadas de API diretas que incluam suas credenciais. A publicação automática por RSS em todas as outras plataformas não sofreu alteração.
Isso significa que sua conta de desenvolvedor do X não tem créditos de API disponíveis. Acesse [console.x.com](https://console.x.com) → **Billing → Credits** e compre créditos. Mesmo \$5 são suficientes para centenas de chamadas de API. Uma vez carregados, tente sua requisição novamente.
Seu Access Token não tem as permissões corretas. Isso geralmente significa uma de duas coisas:
1. **As permissões do seu app estão definidas como "Read" em vez de "Read and write".** Vá até as Settings do seu app no Developer Console e altere para **Read and write and Direct message**.
2. **Você alterou as permissões depois de vincular sua conta do X.** Access Tokens mantêm as permissões com as quais foram criados. Revincule sua conta do X via OAuth para que o novo token herde as permissões atualizadas.
Nossa equipe de suporte tem prazer em ajudar. Se você tiver dúvidas ou encontrar problemas durante a configuração, entre em contato por [support@ayrshare.com](mailto:support@ayrshare.com) e conduziremos você pelo processo.
## Solução de problemas
Certifique-se de estar enviando os dois headers obrigatórios:
* `X-Twitter-OAuth1-Api-Key`
* `X-Twitter-OAuth1-Api-Secret`
Se você vir um erro de par incompatível (por exemplo, "You provided Api-Key but not Api-Secret"), significa que um dos dois está ausente. Ambos são sempre obrigatórios.
A mensagem de erro dirá qual header específico está ausente.
Se você vir esse erro ao tentar vincular sua conta do X, verifique se adicionou as callback URLs obrigatórias às configurações do seu X Developer App (em Authentication settings > Callback URI / Redirect URL):
* `https://profile.ayrshare.com/social-accounts`
* `https://app.ayrshare.com/social-accounts`
Consulte a [etapa de configuração da Callback URL](#step-3-configure-app-permissions) acima.
Sua conta de desenvolvedor do X não tem créditos de API carregados. Acesse [console.x.com](https://console.x.com) → **Billing → Credits** e compre créditos. Mesmo \$5 são suficientes para centenas de chamadas de API.
Seu Access Token não tem as permissões corretas. Isso geralmente significa:
1. **As permissões do seu app estão definidas como "Read" em vez de "Read and write".** Vá até as Settings do seu app no Developer Console e altere para **Read and write and Direct message**.
2. **Você alterou as permissões depois de vincular sua conta do X.** Access Tokens mantêm as permissões com as quais foram criados. Revincule sua conta do X via OAuth para que o novo token herde as permissões atualizadas.
## Precisa de ajuda?
Se você tiver dúvidas ou encontrar problemas ao configurar sua API key do X, nossa equipe de engenharia terá prazer em ajudar. Você pode nos contatar a qualquer momento em [support@ayrshare.com](mailto:support@ayrshare.com).