Apps de desenvolvedor

​

Visão geral

Se você já tem Apps, pode visualizá-las, editá-las ou excluí-las na página de App do portal do desenvolvedor.

O acesso à X API e à X Ads API requer um conjunto de credenciais de autenticação, também conhecidas como chaves e tokens, que você deve enviar com cada requisição. Essas credenciais podem assumir diferentes formas dependendo do tipo de autenticação exigido pelo endpoint específico que você está utilizando.

Aqui estão as diferentes credenciais que você pode gerar na sua App e como usá-las:

• API Key e Secret: Essencialmente, o nome de usuário e a senha da sua App. Você usará essas credenciais para autenticar requisições que exigem Contexto de usuário do OAuth 1.0a ou para gerar outros tokens, como Access Tokens de usuário ou App Access Token.

• Access Token e Secret: Em geral, Access Tokens representam o usuário em nome de quem você está fazendo a requisição. Os que você pode gerar pelo portal do desenvolvedor representam o usuário proprietário da App. Você usará esses tokens para autenticar requisições que exigem Contexto de usuário do OAuth 1.0a. Se quiser fazer requisições em nome de outro usuário, será necessário usar o 3-legged OAuth (fluxo com 3 partes) para que ele conceda autorização.

• Client ID e Client Secret: Essas credenciais são usadas para obter um Access Token de usuário com autenticação OAuth 2.0. Semelhante ao OAuth 1.0a, os Access Tokens de usuário são usados para autenticar requisições que fornecem informações privadas da conta do usuário ou executam ações em nome de outra conta, mas com escopo granular para maior controle sobre o acesso que o aplicativo cliente tem ao usuário.

• App only Access Token: Você usará este token ao fazer requisições a endpoints que respondem com informações publicamente disponíveis no X.

Além de gerar as chaves e tokens necessários para fazer requisições à X API, você também poderá definir permissões de acesso, documentar o caso de uso ou propósito da App, definir uma URL de callback e modificar outras configurações relacionadas ao seu ambiente de desenvolvimento da App no painel de gerenciamento.

​

Apps e Projetos

Você pode usar Apps e Projetos para organizar seu trabalho com a X Developer Platform por caso de uso. Cada Projeto pode incluir um App com o plano Free da X API, até dois Apps com o plano Basic e até três Apps com o plano Pro.

Se você quiser acessar os novos endpoints da X API v2, será necessário usar chaves e tokens de um App associado a um Projeto.

Se você tem Apps criados antes de lançarmos Projetos, eles aparecerão na seção intitulada “Standalone Apps”. Standalone Apps são Apps fora da estrutura de Projeto. Se você vincular um Standalone App a um Projeto, ele então poderá fazer solicitações aos endpoints v2.

​

Painel do portal do desenvolvedor

Você pode visitar o painel para gerenciar as Apps associadas à sua conta. Para saber mais, visite nossa página de documentação sobre o portal do desenvolvedor. O painel permite que desenvolvedores executem, de forma rápida e fácil, as seguintes tarefas:

• Visualizar suas Standalone Apps existentes e o App ID associado a elas.
• Criar um novo Projeto, App ou Standalone App.
• Excluir um Projeto ou App não utilizado.
• Revisar ou atualizar as configurações de uma App específica, incluindo nome, descrição, site, URL de callback e permissões.
• Regenerar credenciais específicas da App, como API Key & Secret, App Access Token e os Access Tokens de usuário do proprietário da App.

​

Inscrevendo-se para obter acesso

Se você já tem X Apps, pode visualizar e editar suas Apps pelo App dashboard da X, caso esteja conectado à sua conta da X no developer.x.com. Observe que você não precisará criar uma conta para gerenciar quaisquer Apps que foram previamente criadas no developer.x.com.

Se você precisar criar uma nova X App, será necessário ter se inscrito para uma conta de desenvolvedor. Se você for membro de uma team account, deverá ter a função de administrador para criar uma nova App.

​

Rotulagem de conta automatizada para bots

Você pode adicionar um rótulo de Conta automatizada às suas contas de bot para informar aos usuários no X que seu bot é uma conta automatizada. Esses bots executam ações programadas por meio da X API. Ao adicionar um rótulo de Conta automatizada ao seu bot, você gera confiança com seu público, legitima sua conta e se diferencia de bots de spam. Isso ajuda as pessoas no X a entenderem melhor o propósito da sua conta ao interagirem com seu bot.

Para adicionar um rótulo à sua conta de bot, siga estas etapas:

1. Vá para as configurações da sua conta
2. Selecione “Sua conta”
3. Selecione “Automação”
4. Selecione “Gerenciamento de conta”
5. Em seguida, selecione a conta do X que executa seu bot
6. Insira sua senha para fazer login
7. Por fim, você deverá ver a confirmação de que o rótulo foi aplicado à sua conta.

---

​

Gerenciamento da App

​

Introdução

O X App dashboard permite que desenvolvedores executem, de forma rápida e fácil, as seguintes tarefas:

• Visualizar suas Apps e Projetos existentes e seus respectivos App ID.
• Criar um novo Projeto ou uma App autônoma.
• Excluir um Projeto, uma App ou uma App autônoma.
• Abrir as configurações de uma App específica clicando na própria App. Nas configurações, é possível ver os detalhes da App, chaves e tokens e permissões.
• Atualizar as configurações de autenticação de usuário da sua App para usar OAuth 1.0a ou OAuth 2.0.

Observação:

Todas as chaves e tokens da App não estão mais visíveis no portal do desenvolvedor e devem ser salvos com segurança assim que forem gerados. Recomendamos usar um gerenciador de senhas para armazenar suas chaves e tokens.

Você pode revelar uma dica da sua API Key para ajudar a corresponder sua credencial à App correta.

​

Configurações do App

​

Detalhes da App

Aqui você pode editar o ícone da App, o nome da App, a descrição da App, a URL do seu site, callback URLs/redirect URIs, URL dos termos de serviço, URL da política de privacidade, nome da organização, URL da organização e a finalidade ou caso de uso da App.

OAuth 2.0 e OAuth 1.0a são métodos de autenticação que permitem que os usuários façam login na sua App com a X. Eles também permitem que sua App faça solicitações específicas em nome de usuários autenticados. Você pode ativar um ou ambos os métodos para sua App.

É importante manter essas informações atualizadas. O nome da sua App e a URL do site serão exibidos como a fonte nos metadados de quaisquer Tweets criados programaticamente pela sua aplicação. Se você mudar o caso de uso de uma X App, certifique-se de atualizá-lo nessas configurações para garantir a conformidade com os Developer Terms.

Se sua aplicação tiver uma tag exibindo “suspended”, isso ocorre porque sua App está em violação de um ou mais developer terms da X, como nossas regras de automação. A equipe de políticas da plataforma para desenvolvedores se comunicará com os desenvolvedores por meio do endereço de e-mail configurado na conta X do proprietário da App. Para revisar esse endereço de e-mail, verifique suas configurações da conta X. E-mails de notificação sobre suspensões serão enviados para esse endereço com um título semelhante a “Application suspension notice” e conterão informações específicas sobre o que fazer em seguida. Para trabalhar com a equipe da X na resolução de suspensões, verifique seu e-mail para instruções específicas ou use nosso platform help form.

​

Chaves e tokens

Dentro de uma App em um Projeto ou por meio de uma App independente, você pode visualizar, regenerar ou revogar os seguintes tokens:

• API Key (Consumer Key) e API Secret (Consumer Secret)
• App Access Token
• User Access Token e Access Token Secret - O Access Token e o Secret disponíveis no portal do desenvolvedor correspondem ao usuário proprietário da App.

Atenção - Se você quiser fazer solicitações em nome de um usuário diferente (ou seja, que não seja o proprietário da App), será necessário usar o 3-legged OAuth (fluxo com 3 partes) do OAuth 1.0a ou o fluxo de OAuth 2.0 Authorization Code com PKCE para gerar um conjunto de Access Tokens do usuário. Em seguida, use esses tokens específicos do usuário na sua solicitação à API.

​

Configurações de autenticação do usuário

Você pode definir as configurações de autenticação da sua App como OAuth 1.0a ou OAuth 2.0. OAuth 2.0 pode ser usado apenas com a X API v2. OAuth 2.0 permite escolher escopos mais granulares, que concedem permissões específicas em nome de um usuário. OAuth 1.0a pode ser usado com a X API v1.1 e v2 e utiliza uma autorização mais ampla, com escopos menos granulares.

​

Permissões de aplicativo-usuário do OAuth 1.0a

Se você é o proprietário da App, pode ajustar as permissões da App (somente leitura; leitura e escrita; ou leitura, escrita e mensagens diretas). Isso controla quais recursos e eventos você pode acessar por meio da X API (observação: alguns recursos exigem permissão adicional diretamente da X).

Você também pode ativar ou desativar, nesta página, a capacidade das suas Apps de solicitar endereços de e-mail dos usuários (isso requer que uma URL dos Termos de Serviço e uma URL da Política de Privacidade estejam presentes na página “App details”).

​

Tipo de App para OAuth 2.0

Se você selecionar OAuth 2.0 como método de autenticação de usuário, será necessário escolher o tipo de App que está criando. As opções são Native App, Single page App, Web App, Automated App ou bot. Native App e Single page App são clientes públicos, e Web App e Automated App ou bots são clientes confidenciais.

Clientes confidenciais se autenticam com segurança no servidor de autorização. Eles mantêm seu client secret protegido. Clientes públicos são aplicativos que geralmente rodam em um navegador ou em um dispositivo móvel e não conseguem usar seus client secrets. Se você selecionar um tipo de App que seja um cliente confidencial, você receberá um client secret.

---

​

Permissões da App

​

Permissões de App do OAuth 1.0a

As permissões de App descrevem o nível de acesso para a autenticação aplicativo-usuário do OAuth 1.0a. As permissões de App são configuradas por aplicativo nas configurações do seu X App.

Há três níveis de permissão disponíveis:

1. Somente leitura
2. Leitura e escrita
3. Leitura, escrita e acesso a Mensagens diretas

Existe uma permissão adicional para solicitar a visualização do endereço de e-mail de um usuário — ela pode ser combinada com qualquer um dos três níveis listados acima.

Se um nível de permissão for alterado, quaisquer tokens de usuário já emitidos para esse X App devem ser descartados e os usuários devem autorizar novamente o App para que o token herde as permissões atualizadas.

Uma boa prática é solicitar apenas o nível mínimo de acesso aos dados da conta do usuário necessário para o funcionamento do aplicativo ou serviço.

​

Somente leitura

Este nível de permissão permite acesso de leitura aos recursos do X, incluindo (por exemplo) os Tweets de um usuário, a linha do tempo inicial e as informações de perfil. Ele não permite ler as Mensagens diretas de um usuário nem atualizar qualquer elemento ou objeto.

​

Leitura e escrita

Este nível de permissão permite acesso de leitura e escrita aos recursos do X. Além do acesso de leitura, também permite publicar Tweets, seguir usuários ou atualizar elementos das informações do perfil de um usuário. Também permite ocultar respostas em nome do usuário autenticado. Este nível de permissão não permite nenhum acesso a Mensagens diretas (incluindo leitura, escrita ou delete).

​

Ler, escrever e acessar Mensagens diretas

Este nível de permissão inclui tudo o que foi mencionado acima e adiciona a capacidade de ler, escrever e excluir Mensagens diretas em nome de um usuário.

• POST /2/dm_conversations/:dm_conversation_id/messages
• POST /2/dm_conversations/
• POST /2/dm_conversations/with/:participant_id/messages
• GET /2/dm_conversations/with/:user_id/dm_events
• GET /2/dm_conversations/:dm_conversation_id/dm_events
• GET /2/dm_events

​

Determinação de permissões

Todas as requisições à API autenticadas retornam um cabeçalho x-access-level na resposta HTTP. O valor desse cabeçalho indica o nível de permissão atualmente em uso. Os valores possíveis são read, read-write e read-write-directmessages.

---

​

URLs de callback

Os métodos de autenticação Contexto de usuário do OAuth 1.0a e OAuth 2.0 Authorization Code com PKCE permitem que desenvolvedores façam solicitações em nome de diferentes usuários do X que passaram por um fluxo específico de login. Atualmente, há dois fluxos que você pode usar para permitir que os usuários autorizem seu aplicativo:

• Fluxo de código de autorização do OAuth 2.0 com PKCE
• Fluxo 3-legged OAuth do OAuth 1.0a (e, separadamente, o fluxo Sign in with X)

Conforme os usuários passam por esses fluxos, eles precisam de uma página da web ou local para onde serão enviados depois de fazer login com sucesso e conceder autorização ao App do desenvolvedor. Essa página ou local de acompanhamento é chamada de URL de callback.

Ao configurar esses fluxos para que seus possíveis usuários os utilizem, os desenvolvedores devem enviar uma URL de callback com suas solicitações para os endpoints de autenticação que compõem os fluxos mencionados anteriormente. Por exemplo, desenvolvedores usando o Contexto de usuário do OAuth 1.0a devem passar o parâmetro callback_url ao fazer uma solicitação para o endpoint GET oauth/request_token. Da mesma forma, desenvolvedores usando OAuth 2.0 Authorization Code com PKCE devem passar o parâmetro redirect_uri com sua solicitação para o endpoint GET oauth2/authorize.

Além de usar esses parâmetros, o desenvolvedor também deve garantir que a URL de callback tenha sido adicionada à allowlist de URLs de callback da App, que pode ser encontrada na página de configurações da App no portal do desenvolvedor.

Se tudo estiver configurado corretamente, os usuários serão redirecionados para a URL de callback após fazerem login com sucesso no X como parte desses fluxos.

​

Pontos a considerar

Ao configurar seus URLs de callback, há alguns pontos a considerar:

Faça o HTTP encode dos parâmetros de query

Como você está passando o URL de callback como um parâmetro de query usando callback_url ou redirect_uri, certifique-se de aplicar HTTP encode ao URL.

Limites de URL de callback

Há um limite fixo de 10 URLs de callback no painel do X Apps. Seu URL de callback deve sempre corresponder exatamente ao URL de callback autorizado que você adiciona no painel de Apps e ao parâmetro que você inclui no fluxo de autorização.

Se você quiser incluir dados específicos da solicitação no URL de callback, use o parâmetro state para armazenar dados que serão incluídos após o redirecionamento do usuário. Você pode codificar os dados no próprio parâmetro state ou usar o parâmetro como um ID de sessão para armazenar o estado no servidor.

Não use localhost como URL de callback Em vez de usar localhost, use um host personalizado localmente ou http(s)://127.0.0.1

URLs de protocolo personalizado Se você quiser aproveitar o deep linking em dispositivos móveis, utilize URLs de protocolo personalizado com partes de caminho e domínio, como twitter://callback/path. No entanto, há uma lista de protocolos não permitidos que você deve evitar. Você pode consultar a lista de protocolos não permitidos abaixo.

Protocolos não permitidos

vbscript	ldap
javascript	mailto
vbs	mmst
data	mmsu
mocha	msbd
keyword	rtsp
livescript	mso-offdap
ftp	snews
file	news
gopher	nntp
acrobat	outlook
callto	stssync
daap	rlogin
itpc	telnet
itms	tn3270
firefoxurl	shell
hcp	sip

​

Exemplo de erro

Se você usar uma URL de callback que não foi adicionada corretamente às configurações da sua App no portal do desenvolvedor, receberá a seguinte mensagem de erro:

OAuth 1.0a

HTTP 403 - Forbidden

{
  "errors": [
    {
      "code":415,"message":"URL de callback não aprovada para este App cliente. URLs de callback aprovadas podem ser ajustadas nas configurações do seu App."
    }
  ]
}

OU

<?xml version="1.0" encoding="UTF-8"?>
<hash>
<error>URL de callback não aprovada para esta aplicação cliente. URLs de callback aprovadas podem ser ajustadas nas configurações da sua aplicação</error>
<request>/oauth/request_token</request>
</hash>

OAuth 2.0

HTTP 400

{
  "error": "invalid_request",
  "error_description": "O valor fornecido para o redirect_uri não correspondeu ao URI do código de autorização."
}

Solução de problemas

Se você receber um erro, verifique se a URL de callback usada nas suas solicitações de autenticação está codificada (URL-encoded) e se corresponde a uma URL de callback adicionada à allowlist da App cujas chaves e tokens você está usando na solicitação.

---