Authentication

Stocktwits uses OAuth 2.0 for authentication and authorization. OAuth 2.0 is a popular open standard used by many API providers. OAuth 2.0 allows users to authorize your application without sharing their username and password. Learn more about OAuth

The Stocktwits API allows you to get permission from a Stocktwits user to access user data on their behalf. By default, your application can only access the user's public data. If your application needs to read more private data or change associated data, your application can request a larger permission scope through the authorization flow.

Server side OAuth flow: (preferred)

1. Register your application to get an API key and secret. Your API consumer key is your client_id and you API consumer secret is your client_secret.
2. Your application requests authorization by redirecting your user to https://api.stocktwits.com/api/2/oauth/authorize with your client_id, response_type set to 'code' and the URL the user should be redirected back to after the authorization process (redirect_uri). Scopes can also be passed (scope) in a comma-delimited list to request further permissions. View the authorize call. Enter the following URL into your browser or direct your users to it for authentication:

   https://api.stocktwits.com/api/2/oauth/authorize?client_id=<client_id>&response_type=code&redirect_uri=http://www.example.com&scope=read,watch_lists,publish_messages,publish_watch_lists,direct_messages,follow_users,follow_stocks
   

3. Stocktwits will prompt an authentication box asking the user whether it's okay to give access to your application.
4. If the user authorizes your application, Stocktwits redirects the user back to the redirect URI you specified with a verification token passed as a query parameter named code. This code can then be exchanged for an access token.

   http://www.example.com/?code=<code>
   

5. To exchange the code for an access token, you must send a POST request to https://api.stocktwits.com/api/2/oauth/token with the code, client_id, client_secret, and redirect_uri. View the token call

   https://api.stocktwits.com/api/2/oauth/token?client_id=<client id>&client_secret=<client secret>&code=<code>&grant_type=authorization_code&redirect_uri=http://www.example.com
   

6. The response will return with an access_token, scope, user_id and username.

   {
     "user_id": 1,
     "access_token": "<access_token>",
     "scope": "read",
     "username": "userabc"
   }
   
   

7. Your application can now use the access token returned to make authenticated API requests to the Stocktwits API. The token can be passed to API endpoints either through a query parameter or with an HTTP Authorization header (see request types below). You may want to store this access token; this access token will not refresh, so you can use it indefinitely on behalf of the authenticated user.

Client side OAuth flow:

1. Register your application to get an API key and secret. Your API consumer key is your client_id and you API consumer secret is your client_secret.
2. Your application requests authorization by redirecting your user to https://api.stocktwits.com/api/2/oauth/authorize with your client_id, response_type set to 'token' and the URL the user should be redirected back to after the authorization process (redirect_uri). Scopes can also be passed (scope) in a comma-delimited list to request further permissions. View the authorize call

   https://api.stocktwits.com/api/2/oauth/authorize?client_id=<client_id>&response_type=token&redirect_uri=http://www.example.com&scope=read,watch_lists,publish_messages,publish_watch_lists,follow_users,follow_stocks
   

3. Stocktwits will prompt an authentication box asking the user whether it's okay to give access to your application.
4. If the user authorizes your application, Stocktwits redirects the user back to the redirect URI you specified with the access token passed as a URL hash parameter.

   http://www.example.com#access_token=<access_token>
   
   

5. If your application is pure Javascript, the token can be easily parsed from the URL. If your application is a native phone application then perform the flow in an embedded webview, redirecting the user to a dummy website. The token can then be retrieved from the URL and the browser can be closed. Your application can now use the access token returned to make authenticated API requests to the Stocktwits API. The token can be passed to API endpoints either through a query parameter or with an HTTP Authorization header (see request types below). You may want to store this access token; this access token will not refresh, so you can use it indefinitely on behalf of the authenticated user.

Request types

The Stocktwits API supports two methods of accessing protected resources. All requests must be SSL.

Query Parameter

curl https://api.stocktwits.com/api/2/streams/trending.json?access_token=<access_token>

Authorization Header

curl -H 'Authorization: OAuth <access_token>' https://api.stocktwits.com/api/2/streams/trending.json

---

Authorize Response Types

This will depend on the OAuth flow you choose and will be the type of response you will want to receive back.

Authorize Application Permissions or Scopes

By default, when authorizing your application, a user only grants your app access to their basic public information. If you want to read additional data or write data to Stocktwits, you need to request additional permissions.

How does this look to a user and what are the permissions?

Token Grant Types

API Reference

• oauth/authorize

• oauth/token