Setting up OAuth2 authorization for the 1C-Bitrix API

Configuring OAuth2 Authorization for the 1C-Bitrix API

When an external application accesses the 1C-Bitrix REST API, the simplest approach is to use a webhook with a token in the URL. For production integrations, however, this is unacceptable: a token in the URL is logged on proxy servers, in access logs, and in browser history. OAuth2 solves this problem through short-lived access tokens and a separate authorisation channel.

How OAuth2 Works in 1C-Bitrix

1C-Bitrix implements the Authorization Code Flow — the standard OAuth2 grant for server-side applications. The flow:

1. The application redirects the user to https://your-portal.ru/oauth/authorize/?client_id={id}&response_type=code&redirect_uri={uri}&scope={scopes}
2. The user authenticates and grants access
3. 1C-Bitrix redirects to redirect_uri?code={authorization_code}
4. The application exchanges the code for tokens: POST /oauth/token/ with grant_type=authorization_code
5. 1C-Bitrix returns an access_token (TTL: 1 hour) and a refresh_token (TTL: 90 days)

The access token is passed in the header: Authorization: Bearer {access_token}.

Registering an Application

An application is registered in the admin area: Marketplace → Applications → Add Application. For on-premise installations, it can also be done via the API: the b_rest_app table stores registered applications.

Registration requires:

• client_id and client_secret (generated automatically)
• redirect_uri — must match exactly when requesting a code (including trailing slash)
• scope — list of permissions: crm, catalog, sale, user, etc.

Token Refresh

An access token lives for 1 hour. After expiry, a new one must be requested using the refresh token:

POST /oauth/token/
grant_type=refresh_token
&client_id={id}
&client_secret={secret}
&refresh_token={refresh_token}

If the refresh token has also expired (90 days of non-use), user re-authentication is required. For service integrations without a user context, use the Client Credentials Flow via webhooks with fixed tokens, or configure a service user and automatically renew the refresh token.

Token Storage

Refresh tokens are long-lived secrets. They must never be stored in code or in repository configuration files. Storage options:

• Encrypted in the application database (AES-256)
• In a secrets management service (HashiCorp Vault, AWS Secrets Manager)
• For simple integrations — in a file outside the web root with permissions 600

On the 1C-Bitrix side, tokens are stored in b_rest_auth. TTL and status can be checked via an SQL query or through \Bitrix\Rest\OAuthService.

Common Configuration Errors

redirect_uri mismatch. OAuth2 requires an exact URI match. https://app.example.com/callback and https://app.example.com/callback/ are different URIs. 1C-Bitrix will return error: redirect_uri_mismatch.

Overly broad scope. Requesting * (all permissions) is poor security practice. Request the minimum necessary set of permissions. If the integration only reads the catalog — request only catalog.

Refresh token not being updated. When a new access token is obtained via refresh, 1C-Bitrix also issues a new refresh token. If the application saves only the old refresh token, authorisation will break after 90 days.

Estimated Timelines

Pricing is calculated individually after analysing the requirements and architecture of the integrated systems.