Development of Local Applications for Bitrix24
A local application in Bitrix24 is the fastest way to start developing an integration: no need to go through Market moderation, no need for a public domain at the start (ngrok will do), no need to register as a developer. Everything is set up directly in the portal settings in 15 minutes.
Typical scenario: you need to connect Bitrix24 to an internal company system — 1C, a warehouse program, or an in-house CRM. External access is restricted, publishing to the Market makes no sense. Local applications are designed exactly for such tasks.
Registering a local application
Portal path: Applications → Developers → Other → Local Application.
Parameters on creation:
-
Authorization type:
Server application(OAuth) orJavaScript application(JS SDK without a server part) - Handler URL: the address of your application where Bitrix24 will open the iframe when launched
- Start URL: URL to start the application from the menu (can match the Handler URL)
-
Permissions: a set of scopes —
crm,task,user,disk,catalog, etc.
After creation you receive client_id and client_secret. For the JavaScript type the secret is not needed — the token is generated on the portal and passed to the iframe via request parameters.
Difference between JavaScript and server types
| Parameter | JavaScript application | Server application |
|---|---|---|
| Authorization | Token from URL parameters/postMessage | OAuth 2.0 Authorization Code |
| Server part | Not required | Mandatory |
| Secret storage | No secret | client_secret on the server |
| Background operation | No | Yes (cron, queues) |
| Event subscription | Via BX24.js | Via event.bind REST |
| When to use | UI widgets, dashboards | Synchronization, automation |
Developing a JavaScript-type local application
Minimal working example:
<!DOCTYPE html>
<html>
<head>
<script src="//api.bitrix24.com/api/v1/"></script>
</head>
<body>
<div id="app"></div>
<script>
BX24.init(function() {
var auth = BX24.getAuth();
// auth.domain — portal domain
// auth.access_token — token for REST requests
BX24.callMethod('user.current', {}, function(result) {
if (result.error()) {
document.getElementById('app').innerHTML = 'Error: ' + result.error();
return;
}
var user = result.data();
document.getElementById('app').innerHTML =
'Hello, ' + user.NAME + '!';
});
BX24.fitWindow();
});
</script>
</body>
</html>
The file //api.bitrix24.com/api/v1/ is the Bitrix24 JS SDK, loaded from the Bitrix CDN. There is no need to connect it directly from the portal.
Developing the server type
For a server-type local application you need an HTTPS endpoint (ngrok works fine for development):
ngrok http 3000
# Result: https://abc123.ngrok.io
This URL is specified as the Handler URL in the application settings.
Handling the OAuth callback in Node.js:
const express = require('express');
const axios = require('axios');
const app = express();
// Handler URL — entry point
app.get('/', (req, res) => {
const { AUTH_ID, REFRESH_ID, AUTH_EXPIRES, DOMAIN, PLACEMENT } = req.query;
// Save tokens
saveTokens({
domain: DOMAIN,
accessToken: AUTH_ID,
refreshToken: REFRESH_ID,
expiresIn: parseInt(AUTH_EXPIRES)
});
res.sendFile(__dirname + '/public/index.html');
});
// Refresh token endpoint
app.post('/refresh', async (req, res) => {
const { refresh_token, domain } = req.body;
const response = await axios.post(
`https://${domain}/oauth/token/`,
new URLSearchParams({
grant_type: 'refresh_token',
client_id: process.env.CLIENT_ID,
client_secret: process.env.CLIENT_SECRET,
refresh_token
})
);
res.json(response.data);
});
Permissions and scopes
Local applications request permissions during installation. If a new scope needs to be added after registration — the user must reinstall the application (click the permissions update button). This is an important UX point: plan permissions in advance, especially if the application is already in production.
Main scopes:
crm — deals, leads, contacts, companies
task — tasks and projects
user — portal users
disk — files and folders
calendar — calendar events
sonet_group — groups and workspaces
catalog — product catalog
sale — store and orders
telephony — calls and telephony
Limitations of local applications
- Work on a single portal only
- Cannot be published to the Market
- Reconfiguration required if the portal domain changes
- No support for multiple redirect_uri values
For most in-house integrations these limitations are insignificant. If scaling is needed in the future — local application code can be migrated to a commercial application without a major rewrite.
Development timelines
| Task | Timeline |
|---|---|
| Local application setup + basic authorization | 0.5–1 day |
| Simple widget (read-only CRM data) | 1–3 days |
| Integration with an internal system (two-way) | 1–3 weeks |
| Full corporate application | 1–2 months |
Local applications are the optimal starting point for an MVP: fast deployment, minimal bureaucracy, full access to the REST API. Transitioning to a commercial format when needed takes 2–3 additional days of work.