Indice di riferimento API OAuth

​

OAuth 1.0a

Scopo	Metodo
Fase 1 del flusso OAuth a 3 vie e Sign in with X Consente a un’applicazione Consumer di ottenere un OAuth Request Token per richiedere l’autorizzazione dell’utente.	POST oauth/request_token
Fase 2 del flusso OAuth a 3 vie e Sign in with X Consente a un’applicazione Consumer di usare un OAuth Request Token per richiedere l’autorizzazione dell’utente.	GET oauth/authenticate
Fase 2 del flusso OAuth a 3 vie e Sign in with X Consente a un’applicazione Consumer di usare un OAuth Request Token per richiedere l’autorizzazione dell’utente.	GET oauth/authorize
Fase 3 del flusso OAuth a 3 vie e Sign in with X Consente a un’applicazione Consumer di scambiare l’OAuth Request Token con un OAuth Access Token.	POST oauth/access_token
Consente a un’applicazione registrata di revocare un OAuth Access Token emesso.	POST oauth/invalidate_token

​

OAuth 2.0 Bearer Token

Scopo	Metodo
Consente a un’App registrata di generare un OAuth 2 app-only Bearer Token, utilizzabile per effettuare richieste API per conto dell’App, senza contesto utente.	POST oauth2/token
Consente a un’App registrata di revocare un OAuth 2 app-only Bearer Token emesso.	POST oauth2/invalidate_token

​

POST oauth/request_token

Consente a un’applicazione Consumer di ottenere un OAuth Request Token per richiedere l’autorizzazione dell’utente. Questo metodo soddisfa la Sezione 6.1 del flusso di autenticazione OAuth 1.0.

È obbligatorio utilizzare HTTPS per tutte le fasi di autorizzazione OAuth.

Nota d’uso: per oauth_nonce sono accettati solo valori ASCII

Resource URL

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

Resource Information

Formati di risposta	JSON
Richiede autenticazione?	No
Soggetto a limite di velocità?	Sì

Parameters

Nome	Obbligatorio	Descrizione	Esempio
oauth_callback	obbligatorio	Per conformità a OAuth 1.0a questo parametro è obbligatorio. Il valore specificato qui verrà utilizzato come URL a cui l’utente verrà reindirizzato qualora approvi l’accesso della tua applicazione al proprio account. Imposta questo valore su oob per la modalità PIN out-of-band. Questo è anche il modo in cui specifichi callback personalizzati da utilizzare nelle applicazioni desktop/mobile. Invia sempre un oauth_callback in questa fase, indipendentemente da un callback preregistrato. Richiediamo che qualsiasi URL di callback utilizzato con questo endpoint sia configurato nelle impostazioni dell’App su developer.x.com*	http://themattharris.local/auth.php twitterclient://callback
x_auth_access_type	opzionale	Sostituisce il livello di accesso richiesto da un’applicazione all’account di un utente. I valori supportati sono read o write. Questo parametro consente a uno sviluppatore di registrare un’applicazione read/write e, quando opportuno, richiedere l’accesso in sola lettura.

Scopri di più su come approvare i tuoi URL di callback in questa pagina.

Nota bene - Puoi visualizzare e modificare le X App esistenti tramite la dashboard X App se hai effettuato l’accesso al tuo account X su developer.x.com.

Example request

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

Request POST Body: N/D

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

Consente a un’App Consumer di utilizzare un OAuth Request Token per richiedere l’autorizzazione dell’utente. Questo metodo soddisfa la Sezione 6.2 del flusso di autenticazione OAuth 1.0. Le applicazioni desktop devono utilizzare questo metodo (e non possono utilizzare GET oauth/authenticate).

Nota d’uso: Un oauth_callback non viene mai inviato a questo metodo; fornirlo invece a POST oauth/request_token.

Resource URL

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

Resource Information

Formati di risposta	JSON
Richiede autenticazione?	Sì
Soggetto a limite di velocità?	Sì

Parameters

Nome	Obbligatorio	Descrizione	Valore predefinito	Esempio
force_login	facoltativo	Forza l’utente a inserire le proprie credenziali per garantire che venga autorizzato l’account corretto.
screen_name	facoltativo	Compila in anticipo il campo del nome utente nella schermata di accesso OAuth con il valore fornito.

Example request

Inviare l’utente al passaggio oauth/authorize in un browser web, includendo un parametro oauth_token: https://api.x.com/oauth/authorize?oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik

​

GET oauth/authenticate

Consente a un’applicazione Consumer di utilizzare un request_token OAuth per richiedere l’autorizzazione dell’utente.

Questo metodo sostituisce la Sezione 6.2 del flusso di autenticazione OAuth 1.0 per le applicazioni che utilizzano il flusso di autenticazione con callback. Il metodo utilizzerà l’utente attualmente connesso come account per l’autorizzazione all’accesso, a meno che il parametro force_login non sia impostato su true.

Questo metodo differisce da GET oauth/authorize in quanto, se l’utente ha già concesso all’applicazione l’autorizzazione, il reindirizzamento avverrà senza che l’utente debba approvare nuovamente l’applicazione. Per ottenere questo comportamento, è necessario abilitare l’impostazione Use Sign in with X nella scheda dell’applicazione.

Resource URL

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

Resource Information

Response formats	JSON
Requires authentication?	Yes
Rate limited?	Yes

Parameters

Name	Required	Description	Default Value	Example
force_login	optional	Obbliga l’utente a inserire le proprie credenziali per garantire che venga autorizzato l’account utente corretto.		true
screen_name	optional	Precompila il campo del nome utente nella schermata di login OAuth con il valore fornito.

Example request

Invia l’utente alla fase oauth/authenticate in un browser web, includendo un parametro oauth_token: https://api.x.com/oauth/authenticate?oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik

​

POST oauth/access_token

Consente a un’app Consumer di scambiare l’OAuth Request Token con un OAuth Access Token. Questo metodo soddisfa la sezione 6.3 del flusso di autenticazione OAuth 1.0.

URL della risorsa

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

Informazioni sulla risorsa

Formati di risposta	JSON
Richiede autenticazione?	Sì
Soggetto a limite di velocità?	Sì

Parametri

Nome	Obbligatorio	Descrizione	Valore predefinito	Esempio
oauth_token	obbligatorio	L’oauth_token qui deve essere lo stesso oauth_token restituito nello step request_token.
oauth_verifier	obbligatorio	Se si utilizza il web flow di OAuth, impostare questo parametro al valore di oauth_verifier restituito nell’URL di callback. Se si utilizza OAuth out-of-band, impostare questo valore al PIN. Per la conformità a OAuth 1.0a questo parametro è obbligatorio. OAuth 1.0a è applicato rigorosamente e le applicazioni che non utilizzano oauth_verifier non completeranno il flusso OAuth.

Esempio di richiesta

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

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

Esempio di risposta

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

​

POST oauth/invalidate_token

Consente a un’App registrata di revocare un access_token OAuth emesso presentando le proprie credenziali client. Una volta che un access_token è stato invalidato, i tentativi successivi di creazione restituiranno un Access Token diverso e l’utilizzo del token invalidato non sarà più consentito.

Resource URL

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

Resource Information

Response formats	JSON
Requires authentication?	Sì - contesto utente con gli Access Tokens che desideri invalidare
Rate limited?	Sì

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"'

Esempio di risposta

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

        {"access_token":"ACCESS_TOKEN"}

Esempio di risposta di errore dopo l’invalidazione del token

        HTTP/1.1 401 Authorization Required
        ...

        {"errors": [{
          "code": 89,
          "message": "Token non valido o scaduto."}
        ]}

​

POST oauth2/token

Consente a un’App registrata di ottenere un Bearer Token OAuth 2, che può essere utilizzato per effettuare richieste API per conto dell’App stessa, senza contesto utente. Questo è chiamato autenticazione solo applicazione.

Un Bearer Token può essere invalidato utilizzando oauth2/invalidate_token. Una volta che un Bearer Token è stato invalidato, i nuovi tentativi di creazione restituiranno un Bearer Token diverso e l’uso del token precedente non sarà più consentito.

Può esistere un solo Bearer Token attivo per un’App e richieste ripetute a questo metodo restituiranno lo stesso token già esistente finché non sarà stato invalidato.

Le risposte corrette includono una struttura JSON che descrive il Bearer Token assegnato.

I token ricevuti con questo metodo devono essere memorizzati in cache. Se tentate troppo frequentemente, le richieste verranno rifiutate con HTTP 403 e codice 99.

URL della risorsa

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

Informazioni sulla risorsa

Formati di risposta	JSON
Richiede autenticazione?	Sì - Basic auth con la tua API Key come nome utente e la secret della tua API Key come password
Con limite di velocità?	Sì

Parametri

Nome	Obbligatorio	Descrizione	Valore predefinito	Esempio
grant_type	obbligatorio	Specifica il tipo di grant richiesto dall’App. Al momento è consentito solo client_credentials. Vedi autenticazione solo applicazione per maggiori informazioni.		client_credentials

Esempio di richiesta

    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

Esempio di risposta:

    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

Consente a un’app registrata di revocare un OAuth 2.0 Bearer Token emesso presentando le proprie credenziali client. Una volta invalidato un Bearer Token, i nuovi tentativi di creazione restituiranno un Bearer Token diverso e l’utilizzo del token invalidato non sarà più consentito.

Le risposte con esito positivo includono una struttura JSON che descrive il Bearer Token revocato.

Resource URL

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

Resource Information

Response formats	JSON
Requires authentication?	Sì - OAuth 1.0a con le consumer API keys dell’App e l’access token e access token secret del proprietario dell’App
Rate limited?	Sì

Parameters

Name	Required	Description
access_token	required	Il valore del Bearer Token che desideri invalidare

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"'

Esempio di risposta

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