Developer Apps

​

Overview

If you have existing Apps, you can view, edit, or delete them via the developer portal’s App page.

Accessing the X API and X Ads API requires a set of authentication credentials, also known as keys and tokens, that you must pass with each request. These credentials can come in different forms depending on the type of authentication that is required by the specific endpoint that you are using.

Here are the different credentials that you can generate in your App and how to use them:

• API Key and Secret: Essentially the username and password for your App. You will use these to authenticate requests that require OAuth 1.0a User Context, or to generate other tokens such as user Access Tokens or App Access Token.

• Access Token and Secret: In general, Access Tokens represent the user that you are making the request on behalf of. The ones that you can generate via the developer portal represent the user that owns the App. You will use these to authenticate requests that require OAuth 1.0a User Context. If you would like to make requests on behalf of another user, you will need to use the 3-legged OAuth flow for them to authorize you.

• Client ID and Client Secret: These credentials are used to obtain a user Access Token with OAuth 2.0 authentication. Similar to OAuth 1.0a, the user Access Tokens are used to authenticate requests that provide private user account information or perform actions on behalf of another account but, with fine-grained scope for greater control over what access the client application has on the user.

• App only Access Token: You will use this token when making requests to endpoints that responds with information publicly available on X.

In addition to generating the keys and tokens necessary to make X API requests, you will also be able to set access permissions, document the use case or purpose for the App, define a callback URL, and modify other settings related to your App developer environment from within the management dashboard.

​

Apps and Projects

You can use Apps and Projects to help organize your work with the X Developer Platform by use case. Each Project can include one App with the Free X API plan, up to two Apps with the Basic plan, and up to three Apps with the Pro plan.

If you would like to access the new X API v2 endpoints, you will be required to use keys and tokens from an App that is associated with a Project.

If you have Apps that were created before we launched Projects, they will be visible in the section entitled “Standalone Apps”. Standalone Apps are Apps outside of the Project structure. If you attach a Standalone App to a Project, it will then be able to make requests to the v2 endpoints.

​

Developer portal dashboard

You can visit the dashboard to manage the Apps associated with your account. To learn more, please visit our documentation page on the developer portal. The dashboard allows developers to quickly and easily perform the following tasks:

• View your existing Standalone Apps and their associated App ID.
• Create a new Project, App, or standalone App.
• Delete an unused Project or App.
• Review or update a specific App’s settings, including updating name, description, website, callback URL, and permissions.
• Regenerate App specific credentials like API Key & Secret, App Access Token, and the App owner’s user Access Tokens.

​

Signing up for access

If you have existing X Apps, you can view and edit your Apps via the X App dashboard if you are logged into your X account on developer.x.com. Please note you will not need to sign up for an account to manage any and all Apps that were previously created on developer.x.com.

If you need to create a new X App, you will need to have signed up for a developer account. If you are a member of a team account, you must be assigned an admin role to create a new App.

​

Automated Account labeling for bots

You can add an Automated Account label to your bot accounts to let users on X know that your bot is an automated account. These bots perform programmed actions through the X API. When you add an Automated Account label to your bot, you build trust with your audience, legitimize your account, and set yourself apart from spammy bots. This helps people on X better understand your account’s purpose when interacting with your bot.

To attach a label to your bot account, follow these steps:

1. Go to your account settings
2. Select “Your account”
3. Select “Automation”
4. Select “Managing account”
5. Next, select the X account, which runs your bot account
6. Enter your password to log in
7. Finally, you should see confirmation that the label has been applied to your account.

​

App management

​

Introduction

The X App dashboard allows developers to quickly and easily perform the following tasks:

• View your existing Apps and Projects and their associated App ID.
• Create a new Project or standalone App.
• Delete a Project, App, or standalone App.
• Open up a specific App’s settings by clicking into the App’s settings. Within the settings, you can see the App details, keys and tokens, and permissions.
• Update your App’s user authentication settings to use either OAuth 1.0a or OAuth 2.0.

​

App Settings

​

App details

Here you can edit the App icon, App name, App description, your website URL, callback URLs/redirect URIs, terms of service URL, privacy policy URL, organization name, organization URL, and purpose or use case of the App.

OAuth 2.0 and OAuth 1.0a are authentication methods that allow users to sign in to your App with X. They also allow your App to make specific requests on behalf of authenticated users. You can turn on one, or both methods for your App.

It is important to keep this information up to date. Your App name and website URL will be shown as the source within metadata for any Tweets created programmatically by your application. If you change the use case of a X App, be sure to update the use case in these settings in order to ensure you are in compliance with the Developer Terms.

If your application has a tag showing ‘suspended’ this is because your app is in violation of one or more of X’s developer terms such as our automation rules. The developer platform policy team will communicate with developers through the email address set up on the App owner’s X account, to review this email address please review your X account settings. Notification emails about suspensions will be sent to this email address with the title similar to “Application suspension notice” and will have specific information on what to do next. To work with the X team to address suspensions, please check your email for specific instructions, or use our platform help form.

​

Keys and tokens

Inside of an App in a Project or via a standalone App you can view, regenerate, or revoke the following tokens:

• API Key (Consumer Key) and API Secret (Consumer Secret)
• App Access Token
• User Access Token and Access Token Secret - The Access Token and Secret available within the developer portal relates to the user that owns the App.

Please note - If you would like to make requests on behalf of a different user (in other words, not the user that owns the App), you will have to use either the OAuth 1.0a 3-legged OAuth flow or OAuth 2.0 Authorization Code with PKCE flow to generate a set of user Access Tokens. You will then use these user-specific tokens in your request to the API.

​

User Authentication Settings

You can select your App’s authentication settings to be OAuth 1.0a or OAuth 2.0. OAuth 2.0 can be used with the X API v2 only. OAuth 2.0 allows you to pick specific fine-grained scopes which give you specific permissions on behalf of a user. OAuth 1.0a can be used with X API v1.1 and v2 and uses broad authorization with coarse scopes.

​

OAuth 1.0a Application-user Permissions

If you are the App owner, you can adjust the permissions of the App (read-only; read and write; or read, write and direct messages). This controls which resources and events you have access to via X APIs (note: some resources require further permission from X directly).

You can also toggle on and off your Apps’ ability to ask for user email addresses on this page (this requires a Terms of Service URL and a Privacy Policy URL to be present on the “App details” page).

​

OAuth 2.0 Type of App

If you select OAuth 2.0 as your user authentication method you will need to select the type of App you are creating. Your options are Native App, Single page App, Web App, Automated App or bot. Native App and Single page Apps are public clients and Web App and Automated App or bots are confidential clients.

Confidential clients securely authenticate with the authorization server. They keep your client secret safe. Public clients are applications usually running in a browser or on a mobile device and are unable to use your client secrets. If you select a type of App that is a confidential client, you will be provided with a client secret.

​

App permissions

​

OAuth 1.0a App permissions

App permissions describe the access level for OAuth 1.0a application-user authentication. App permissions are configured per application within your X App settings.

There are three levels of permission available:

1. Read only
2. Read and write
3. Read, write and access Direct Messages

An additional permission exists to request visibility of a user’s email address - this can be combined with any of the three levels listed above.

If a permission level is changed, any user tokens already issued to that X app must be discarded and users must re-authorize the App in order for the token to inherit the updated permissions.

A good practice is to request only the minimum level of access to a user’s account data that an application or service requires.

​

Read only

This permission level permits read access to X resources, including (for example) a user’s Tweets, home timeline, and profile information. It does not allow access to read a user’s Direct Messages, and it does not allow to update any element or object.

​

Read and write

This permission level permits read and write access to X resources. In addition to allowing read access, it also allow to post Tweets, follow users, or update elements of a user’s profile information. It also allow to hide replies on behalf of the authenticating user. This permission level does not allow any access to Direct Messages (including read, write, or delete).

​

Read, write and access Direct Messages

This permission level includes access to all of the above and adds the ability to read, write and delete Direct Messages on behalf of a user.

• 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

​

Determining permissions

All authenticated API requests return an x-access-level header in the HTTP response. The value of the header shows the current permission level in use. Possible values are read, read-write, and read-write-directmessages.

​

Callback URLs

The OAuth 1.0a User Context and OAuth 2.0 Authorization Code with PKCE authentication methods enable developers to make requests on behalf of different X users that have worked through a specific sign-in flow. Currently, there are two flows that you can use to enable users to authorize your application:

• OAuth 2.0 authorization code flow with PKCE
• OAuth 1.0a 3-legged OAuth flow (and separately, the Sign in with X flow)

As users work through these flows, they need a web page or location to be sent to after they have successfully logged in and provided authorization to the developer’s App. This follow-up webpage or location is called a callback URL.

When setting up these flows for their potential users to work through, developers must pass a callback URL with their requests to the authentication endpoints that make up the flows mentioned earlier. For example, developers using OAuth 1.0a User Context must pass the callback_url parameter when making a request to the GET oauth/request_token endpoint. Similarly, developers using OAuth 2.0 Authorization Code with PKCE must pass the redirect_uri parameter with their request to the GET oauth2/authorize endpoint.

In addition to using these parameters, the developer must also make sure that the callback URL has also been added to their App’s callback URL allowlist, which can be found on the developer portal’s App settings page.

If set up properly, developers will be directed to the callback URL after successfully signing in to X as part of these flows.

​

Things to keep in mind

When you are setting up your callback URLs, there are a few things that you should keep in mind:

HTTP encode your query parameters

Since you are passing the callback URL as a query parameter with the callback_url or redirect_uri parameters, please make sure that you HTTP encode the URL.

Callback URL limits

There is a hard limit of 10 callback URLs in the X Apps dashboard. Your callback URL should always be an exact match between your allow listed callback URL that you add to the Apps dashboard and the parameter you add in the authorization flow.

If you wish to include request-specific data in the callback URL, you can use the state parameter to store data that will be included after the user is redirected. It can either encode the data in the state parameter itself or use the parameter as a session ID to store the state on the server.

Don’t use localhost as a callback URL Instead of using localhost, please use a custom host locally or http(s)://127.0.0.1

Custom protocol URLs If you would like to take advantage of mobile deep linking, you can utilize custom protocol URLs with a path and domain part, such as twitter://callback/path. However, we do have a list of disallowed protocols that you will need to avoid. You can review the list of disallowed protocols below.

Disallowed protocols

​

Error Example

If you use a callback URL that hasn’t been properly added to your App’s settings in the developer portal, you will receive the following error message:

OAuth 1.0a

{
  "errors": [
    {
      "code":415,"message":"Callback URL not approved for this client application. Approved callback URLs can be adjusted in your application settings."
    }
  ]
}

OR

<?xml version="1.0" encoding="UTF-8"?>
<hash>
<error>Callback URL not approved for this client application. Approved callback URLs can be adjusted in your application settings</error>
<request>/oauth/request_token</request>
</hash>

OAuth 2.0

{
  "error": "invalid_request",
  "error_description": "Value passed for the redirect uri did not match the uri of the authorization code."
}

Troubleshooting

If you receive an error, please make sure that the callback URL that you are using in your authentication requests is HTTP encoded, and that it matches a callback URL that has been added to the allowlist for the App whose keys and tokens you are using in your request.