Índice de referência da API OAuth

​

OAuth 1.0a

Finalidade	Método
Etapa 1 do fluxo OAuth de 3 etapas e Entrar com o X Permite que um aplicativo Consumer obtenha um OAuth Request Token para solicitar autorização do usuário.	POST oauth/request_token
Etapa 2 do fluxo OAuth de 3 etapas e Entrar com o X Permite que um aplicativo Consumer use um OAuth Request Token para solicitar autorização do usuário.	GET oauth/authenticate
Etapa 2 do fluxo OAuth de 3 etapas e Entrar com o X Permite que um aplicativo Consumer use um OAuth Request Token para solicitar autorização do usuário.	GET oauth/authorize
Etapa 3 do fluxo OAuth de 3 etapas e Entrar com o X Permite que um aplicativo Consumer troque o OAuth Request Token por um OAuth Access Token.	POST oauth/access_token
Permite que um aplicativo registrado revogue um OAuth Access Token emitido.	POST oauth/invalidate_token

​

OAuth 2.0 Bearer Token

Finalidade	Método
Permite que uma App registrada gere um OAuth 2 app-only Bearer Token, que pode ser usado para fazer solicitações à API em nome da App, sem contexto de usuário.	POST oauth2/token
Permite que uma App registrada revogue um OAuth 2 app-only Bearer Token emitido.	POST oauth2/invalidate_token

​

POST oauth/request_token

Permite que um aplicativo Consumer obtenha um OAuth Request Token para solicitar a autorização do usuário. Este método atende à Seção 6.1 do fluxo de autenticação OAuth 1.0.

Exigimos o uso de HTTPS em todas as etapas de autorização OAuth.

Observação de uso: Apenas valores ASCII são aceitos para o oauth_nonce.

Resource URL

https://api.x.com/oauth/request_token

Resource Information

Response formats	JSON
Requires authentication?	No
Rate limited?	Yes

Parameters

Name	Required	Description	Example
oauth_callback	required	Para conformidade com OAuth 1.0a, este parâmetro é obrigatório. O valor especificado aqui será usado como a URL para a qual o usuário será redirecionado caso ele aprove o acesso do seu aplicativo à conta. Defina como oob para o modo de PIN fora de banda. Esta também é a forma de especificar callbacks personalizados para uso em aplicativos desktop/dispositivos móveis. Sempre envie um oauth_callback nesta etapa, independentemente de um callback pré-registrado. Exigimos que qualquer URL de callback usada com este endpoint seja configurada nas configurações da App em developer.x.com*	http://themattharris.local/auth.php twitterclient://callback
x_auth_access_type	optional	Substitui o nível de acesso solicitado por um aplicativo à conta de um usuário. Os valores compatíveis são read ou write. Este parâmetro permite que um desenvolvedor registre um aplicativo de leitura/gravação, mas solicite acesso somente leitura quando apropriado.

Saiba mais sobre como aprovar suas URLs de callback nesta página.

Atenção - Você pode visualizar e editar suas X apps existentes por meio do X app dashboard se estiver conectado à sua conta X em developer.x.com.

Example request

Request URL: POST https://api.x.com/oauth/request_token

Request POST Body: N/A

Authorization Header: OAuth oauth_nonce="K7ny27JTpKVsTgdyLdDfmQQWVLERj2zAK5BslRsqyw", oauth_callback="http%3A%2F%2Fmyapp.com%3A3005%2Ftwitter%2Fprocess_callback", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1300228849", oauth_consumer_key="OqEqJeafRSF11jBMStrZz", oauth_signature="Pc%2BMLdv028fxCErFyi8KXFM%2BddU%3D", oauth_version="1.0"

Response: oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik&oauth_token_secret=Kd75W4OQfb2oJTV0vzGzeXftVAwgMnEK9MumzYcM&oauth_callback_confirmed=true

​

GET oauth/authorize

Permite que um aplicativo Consumer use um OAuth Request Token para solicitar a autorização do usuário. Este método cumpre a Seção 6.2 do fluxo de autenticação OAuth 1.0. Aplicativos desktop devem usar este método (e não podem usar GET oauth / authenticate).

Nota de uso: Um oauth_callback nunca é enviado para este método; forneça-o para POST oauth / request_token.

Resource URL

https://api.x.com/oauth/authorize

Resource Information

Formatos de resposta	JSON
Requer autenticação?	Sim
Sujeito a limite de taxa?	Sim

Parameters

Nome	Obrigatório	Descrição	Valor padrão	Exemplo
force_login	opcional	Obriga o usuário a inserir suas credenciais para garantir que a conta de usuário correta seja autorizada.
screen_name	opcional	Preenche antecipadamente o campo de nome de usuário na tela de login do OAuth com o valor fornecido.

Example request

Envie o usuário para a etapa oauth/authorize em um navegador da web, incluindo o parâmetro oauth_token: https://api.x.com/oauth/authorize?oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik

​

GET oauth/authenticate

Permite que um aplicativo Consumer use um request_token do OAuth para solicitar autorização do usuário.

Este método substitui a Seção 6.2 do fluxo de autenticação OAuth 1.0 para aplicativos que usam o fluxo de autenticação com callback. O método usará o usuário atualmente conectado como a conta para autorização de acesso, a menos que o parâmetro force_login seja definido como true.

Este método difere de GET oauth/authorize porque, se o usuário já concedeu permissão ao aplicativo, o redirecionamento ocorrerá sem que o usuário precise aprovar o aplicativo novamente. Para que esse comportamento ocorra, você deve habilitar a configuração Use Sign in with X no seu registro de aplicativo.

URL do recurso

https://api.x.com/oauth/authenticate

Informações do recurso

Formatos de resposta	JSON
Requer autenticação?	Sim
Com limite de taxa?	Sim

Parâmetros

Nome	Obrigatório	Descrição	Valor padrão	Exemplo
force_login	opcional	Obriga o usuário a inserir suas credenciais para garantir que a conta de usuário correta seja autorizada.		true
screen_name	opcional	Preenche previamente o campo de nome de usuário na tela de login do OAuth com o valor fornecido.

Exemplo de solicitação

Envie o usuário para a etapa oauth/authenticate em um navegador da web, incluindo um parâmetro oauth_token: https://api.x.com/oauth/authenticate?oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik

​

POST oauth/access_token

Permite que um aplicativo Consumer troque o OAuth Request Token por um OAuth Access Token. Este método atende à Seção 6.3 do fluxo de autenticação OAuth 1.0.

Resource URL

https://api.x.com/oauth/access_token

Resource Information

Response formats	JSON
Requires authentication?	Yes
Rate limited?	Yes

Parameters

Name	Required	Description	Default Value	Example
oauth_token	required	O oauth_token aqui deve ser o mesmo oauth_token retornado na etapa request_token.
oauth_verifier	required	Se estiver usando o fluxo web do OAuth, defina este parâmetro como o valor de oauth_verifier retornado na URL de callback. Se estiver usando OAuth fora de banda (out-of-band), defina este valor como o código PIN. Para conformidade com OAuth 1.0a, este parâmetro é obrigatório. O OAuth 1.0a é rigorosamente aplicado e aplicativos que não usarem o oauth_verifier não conseguirão concluir o fluxo do OAuth.

Example request

POST https://api.x.com/oauth/access_token?oauth_token=qLBVyoAAAAAAx72QAAATZxQWU6P&oauth_verifier=ghLM8lYmAxDbaqL912RZSRjCCEXKDIzx

Com PIN (PIN-based) POST https://api.x.com/oauth/access_token?oauth_token=9Npq8AAAAAAAx72QBRABZ4DAfY9&oauth_verifier=4868795

Example response

oauth_token=6253282-eWudHldSbIaelX7swmsiHImEL4KinwaGloHANdrY&oauth_token_secret=2EEfA6BG5ly3sR3XjE0IBSnlQu4ZrUzPiYTmrkVU&user_id=6253282&screen_name=xapi

​

POST oauth/invalidate_token

Permite que uma aplicação registrada revogue um access_token OAuth emitido, apresentando suas credenciais de cliente. Depois que um access_token for invalidado, novas tentativas de criação gerarão um Access Token diferente e o uso do token invalidado não será mais permitido.

Resource URL

https://api.x.com/1.1/oauth/invalidate_token

Resource Information

Response formats	JSON
Requires authentication?	Sim — contexto do usuário com os access tokens que você deseja invalidar
Rate limited?	Sim

Example request

        curl --request POST
          --url 'https://api.x.com/1.1/oauth/invalidate_token.json'
          --header 'authorization: OAuth oauth_consumer_key="CLIENT_KEY",
         oauth_nonce="AUTO_GENERATED_NONCE", oauth_signature="AUTO_GENERATED_SIGNATURE",
         oauth_signature_method="HMAC-SHA1", oauth_timestamp="AUTO_GENERATED_TIMESTAMP",
         oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

Exemplo de resposta

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

        {"access_token":"ACCESS_TOKEN"}

Exemplo de resposta de erro após o token ser invalidado

        HTTP/1.1 401 Authorization Required
        ...

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

​

POST oauth2/token

Permite que uma App registrada obtenha um Bearer Token OAuth 2, que pode ser usado para fazer solicitações à API em nome da própria App, sem contexto de usuário. Isso é chamado de autenticação somente de aplicação.

Um Bearer Token pode ser invalidado usando oauth2/invalidate_token. Depois que um Bearer Token for invalidado, novas tentativas de criação gerarão um Bearer Token diferente e o uso do token anterior não será mais permitido.

Apenas um Bearer Token pode ficar ativo por App; solicitações repetidas a este método retornarão o mesmo token já existente até que ele seja invalidado.

Respostas bem-sucedidas incluem uma estrutura JSON descrevendo o Bearer Token concedido.

Os tokens recebidos por este método devem ser armazenados em cache. Se tentado com muita frequência, as solicitações serão rejeitadas com HTTP 403 e código 99.

URL do recurso

https://api.x.com/oauth2/token

Informações do recurso

Formatos de resposta	JSON
Requer autenticação?	Sim — autenticação Basic com sua API Key como nome de usuário e o segredo da API Key como senha
Possui limite de taxa?	Sim

Parâmetros

Nome	Obrigatório	Descrição	Valor padrão	Exemplo
grant_type	obrigatório	Especifica o tipo de grant solicitado pela App. No momento, apenas client_credentials é permitido. Consulte autenticação somente de aplicação para mais informações.		client_credentials

Exemplo de solicitação

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

    grant_type=client_credentials

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":"AAAA%2FAAA%3DAAAAAAAA"}

​

POST oauth2/invalidate_token

Permite que um aplicativo registrado revogue um OAuth 2.0 Bearer Token emitido apresentando suas credenciais de cliente. Depois que um Bearer Token for invalidado, novas tentativas de criação gerarão um Bearer Token diferente e o uso do token invalidado não será mais permitido.

As respostas bem-sucedidas incluem uma estrutura JSON que descreve o Bearer Token revogado.

Resource URL

https://api.x.com/oauth2/invalidate_token

Resource Information

Response formats	JSON
Requires authentication?	Sim - OAuth 1.0a com as consumer API keys do aplicativo e o access token & access token secret do proprietário do aplicativo
Rate limited?	Sim

Parameters

Name	Required	Description
access_token	required	O valor do Bearer Token que você deseja invalidar

Example request

        curl --request POST
          --url 'https://api.x.com/oauth2/invalidate_token?access_token=AAAA%2FAAA%3DAAAAAAAA'
          --header 'authorization: OAuth oauth_consumer_key="CLIENT_KEY",
         oauth_nonce="AUTO_GENERATED_NONCE", oauth_signature="AUTO_GENERATED_SIGNATURE",
         oauth_signature_method="HMAC-SHA1", oauth_timestamp="AUTO_GENERATED_TIMESTAMP",
         oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

Exemplo de resposta

         Status: 200 OK
         Content-Type: application/json; charset=utf-8
         Content-Length: 135
         ...
       {
        "access_token": "AAAA%2FAAA%3DAAAAAAAA"
        }