Autenticação App only e OAuth 2.0 Bearer Token

​

Autenticação App only e OAuth 2.0 Bearer Token

X oferece às aplicações a capacidade de emitir solicitações autenticadas em nome da própria aplicação, em vez de em nome de um usuário específico. A implementação da X é baseada no fluxo Client Credentials Grant da especificação OAuth 2.

A autenticação somente da aplicação não inclui nenhum contexto de usuário e é uma forma de autenticação em que uma aplicação faz solicitações à API em seu próprio nome. Este método é para desenvolvedores que precisam apenas de acesso de leitura a informações públicas.

Você pode realizar a autenticação somente da aplicação usando as consumer API keys da sua App ou usando um App only Access Token (Bearer Token). Isso significa que as únicas solicitações que você pode fazer a uma X API não devem exigir um usuário autenticado.

Com a autenticação somente da aplicação, você pode executar ações como:

• Obter timelines de usuários
• Acessar amigos e seguidores de qualquer conta
• Acessar recursos de List
• Pesquisar Tweets

Observe que somente OAuth 1.0a ou OAuth 2.0 Authorization Code Flow com PKCE é necessário para emitir solicitações em nome de usuários. A página de API reference descreve o método de autenticação necessário para usar uma API. Você precisará de autenticação de usuário, contexto de usuário, com um access token para realizar o seguinte:

• Publicar Tweets ou outros recursos
• Pesquisar usuários
• Usar qualquer endpoint de geolocalização
• Acessar Mensagens diretas ou credenciais da conta
• Recuperar os endereços de e-mail do usuário

​

Fluxo de autenticação

Para usar este método, você precisa de um App only Access Token (também conhecido como Bearer Token). Você pode gerar um App only Access Token (Bearer Token) enviando sua consumer key e secret ao endpoint POST oauth2/token.

O fluxo de autenticação App only segue estas etapas:

• Um aplicativo codifica sua consumer key e secret em um conjunto de credenciais com codificação específica.
• O aplicativo faz uma solicitação ao endpoint POST oauth2/token para trocar essas credenciais por um App only Access Token.
• Ao acessar a REST API, o aplicativo usa o App only Access Token para autenticar.

Como não é necessário assinar a solicitação, essa abordagem é muito mais simples do que o modelo padrão OAuth 1.0a.

​

Sobre autenticação App only

Tokens são senhas

Lembre-se de que o consumer key & secret e o próprio App only Access Token (Bearer Token) concedem acesso para fazer requisições em nome de uma aplicação. Esses valores devem ser tratados com a mesma sensibilidade que senhas e não devem ser compartilhados nem distribuídos a partes não confiáveis.

SSL obrigatório

Todas as requisições (tanto para obter quanto para usar os tokens) devem usar endpoints HTTPS. Siga as práticas recomendadas detalhadas em Conectando à X API usando TLS — os pares devem sempre ser verificados.

Sem contexto de usuário

Ao fazer requisições usando autenticação App only, não existe o conceito de “usuário atual”. Portanto, endpoints como POST statuses/update não funcionarão com autenticação App only. Consulte usando OAuth para mais informações sobre como emitir requisições em nome de um usuário.

Limites de requisições

As aplicações têm dois tipos de pools de limites de requisições.

Requisições feitas em nome de usuários com access tokens, também conhecidas como contexto de usuário, consomem de um contexto de limites de requisições diferente daquele usado na autenticação App only. Ou seja, requisições feitas em nome de usuários não consumirão dos limites disponíveis por meio da autenticação App only, e requisições feitas por meio da autenticação App only não consumirão dos limites usados na autenticação baseada em usuário.

Leia mais sobre API Rate Limiting e revise os limites.

​

Emissão de solicitações somente da aplicação

Etapa 1: Codificar a consumer key e o consumer secret

As etapas para codificar a consumer key e o consumer secret de uma aplicação em um conjunto de credenciais para obter um Bearer Token são:

1. Faça a codificação de URL da consumer key e do consumer secret de acordo com a RFC 1738. Observe que, no momento desta redação, isso não alterará a consumer key nem o consumer secret, mas esta etapa ainda deve ser realizada caso o formato desses valores mude no futuro.
2. Concatene a consumer key codificada, um caractere de dois-pontos ”:” e o consumer secret codificado em uma única string.
3. Faça a codificação Base64 da string do passo anterior.

Abaixo estão valores de exemplo mostrando o resultado desse algoritmo. Observe que o consumer secret usado nesta página é para fins de teste e não funcionará para solicitações reais.

Consumer key	xvz1evFS4wEEPTGEFPHBog
Consumer secret	L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Consumer key codificada segundo a RFC 1738 (não altera)	xvz1evFS4wEEPTGEFPHBog
Consumer secret codificado segundo a RFC 1738 (não altera)	L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Credenciais do Bearer Token	xvz1evFS4wEEPTGEFPHBog:L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Credenciais do Bearer Token codificadas em Base64	:: eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJnNmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==

Etapa 2: Obter um App only Access Token (Bearer Token)

O valor calculado na etapa 1 deve ser trocado por um App only Access Token ao emitir uma solicitação para POST oauth2/token:

• A solicitação deve ser uma solicitação HTTP POST.
• A solicitação deve incluir um cabeçalho Authorization com o valor Basic <base64 encoded value from step 1>.
• A solicitação deve incluir um cabeçalho Content-Type com o valor application/x-www-form-urlencoded;charset=UTF-8.
• O corpo da solicitação deve ser grant_type=client_credentials.

Exemplo de solicitação (o cabeçalho Authorization foi quebrado em linhas):

POST /oauth2/token HTTP/1.1
Host: api.x.com
User-Agent: My X App v1.0.23
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFK2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29
Accept-Encoding: gzip

grant\_type=client\_credentials

Se a solicitação estiver formatada corretamente, o servidor responderá com um payload codificado em JSON:

Exemplo de resposta:

HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
...
Content-Encoding: gzip
Content-Length: 140

{"token\_type":"bearer","access\_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}

Os aplicativos devem verificar se o valor associado à chave token_type do objeto retornado é bearer. O valor associado à chave access_token é o App only Access Token (Bearer Token).

Observe que um App only Access Token é válido para um aplicativo por vez. Enviar outra solicitação com as mesmas credenciais para /oauth2/token retornará o mesmo token até que ele seja invalidado.

Etapa 3: Autenticar solicitações à API com o App only Access Token (Bearer Token)

O App only Access Token (Bearer Token) pode ser usado para enviar solicitações a endpoints da API que oferecem suporte à autenticação somente de aplicativo. Para usar o App Access Token, faça uma solicitação HTTPS normal e inclua um cabeçalho Authorization com o valor Bearer <base64 bearer token value from step 2>. Signing is not required.

Solicitação de exemplo (o cabeçalho Authorization foi quebrado em várias linhas):

GET /1.1/statuses/user\_timeline.json?count=100&screen\_name=twitterapi HTTP/1.1
Host: api.x.com
User-Agent: Meu X App v1.0.23
Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAA
                      AAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Accept-Encoding: gzip

Invalidando um App only Access Token (Bearer Token)

Se um App only Access Token for comprometido ou precisar ser invalidado por qualquer motivo, faça uma chamada para POST oauth2/invalidate_token.

Exemplo de requisição (o cabeçalho Authorization foi quebrado em linhas):

POST /oauth2/invalidate_token HTTP/1.1
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
User-Agent: Meu X App v1.0.23
Host: api.x.com
Accept: */*
Content-Length: 119
Content-Type: application/x-www-form-urlencoded

access_token=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

Exemplo de resposta:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 127
...

{"access_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}

​

Casos de erro comuns

Esta seção descreve alguns erros comuns na negociação e no uso de Bearer Tokens. Note que nem todas as possíveis respostas de erro estão cobertas aqui — fique atento a códigos e respostas de erro não tratados.

Solicitações inválidas para obter ou revogar um App only Access Token

Tentativas de:

• Obter um App only Access Token (Bearer Token) com uma solicitação inválida (por exemplo, omitindo grant_type=client_credentials).
• Obter ou revogar um App only Access Token (Bearer Token) com credenciais de App incorretas ou expiradas.
• Invalidar um App only Access Token (Bearer Token) incorreto ou já revogado.
• Obter um App only Access Token (Bearer Token) com muita frequência em um curto período.

Resultarão em:

HTTP/1.1 403 Forbidden
Content-Length: 105
Content-Type: application/json; charset=utf-8
...

{"errors":\[{"code":99,"label":"authenticity\_token\_error","message":"Não foi possível verificar suas credenciais"}\]}

​

A solicitação à API contém um App only Access Token inválido (Bearer Token)

Usar um Access Token incorreto ou revogado para fazer solicitações à API resultará em:

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 61
...

{"errors":[{"message":"Token inválido ou expirado","code":89}]}

​

App only Access Token (Bearer Token) usado em endpoint que não oferece suporte à autenticação somente de aplicação

Fazer uma requisição a um endpoint que exige contexto de usuário (como statuses/home_timeline) com um App only Access Token (Bearer Token) resultará em:

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 91
...

{"errors":\[{"message":"Suas credenciais não permitem acesso a este recurso","code":220}\]}