REST-API: Basic Authentication vs. OAuth 2.0

When working with the REST API, different authentication mechanisms can be used depending on the scenario and security requirements. 

For a full overview for all mechanisms, please consult our Developer Guide: API Guide | BOC Developer Portal

Two commonly referenced methods are Basic Authentication and OAuth 2.0, as they provide relatively straightforward approaches.

While both methods allow access to the API, they differ significantly in terms of security model, configuration effort, and intended use cases. Choosing the appropriate method is therefore not only a technical decision but also depends on your organization’s security policies and the type of integration you are implementing.
 

Important: 
The configuration described in this article must be validated against your internal security policies, and only provides best practice recommendations and insights. 

Productive setups should always be implemented and reviewed by experienced IT administrators.

Basic Authentication

Basic Authentication is the simpler of the two approaches. It relies on sending a username and password with each API request. This makes it easy to set up and suitable for quick tests or simple integrations.

However, this simplicity comes with limitations. Since the credentials are transmitted with every request, there is no separation between authentication and authorization beyond the assigned user permissions. In addition, there is no concept of token lifetime or scoped access, which reduces the overall security level compared to OAuth.

For this reason, Basic Authentication is typically only recommended for non-productive scenarios or short-term testing.
 

Documentation: Enabling Basic Authentication - BOC Docs

Basic Authentication Requirements

When using Basic Authentication, the following user conditions must be met:

• The user must be a locally defined user within the system. 
• Users that are imported or authenticated via Single Sign-On (SSO) cannot be used in this context. 
• The user must not be configured as a technical user.
• Configured Repository access.

When using Basic Authentication, the following system conditions must be met:

Access should be restricted on a network level by allowing only specific client IP addresses: Authentication. 

Please note: After configuration, an environment restart has to be triggered: Environment Restart Initiators

OAuth 2.0

OAuth 2.0 provides a more modern and secure authentication mechanism and is therefore the recommended approach for productive environments.

Instead of transmitting user credentials, OAuth uses access tokens. These tokens can be limited in scope and lifetime, which allows for significantly better control over access and reduces the risk associated with credential exposure.

Documentation: Enabling OAuth 2.0 - BOC Docs
 

OAuth 2.0 Flows

Depending on the integration scenario, different OAuth flows are used: 

Client Credentials Grant Type | BOC Developer Portal
The Client Credentials Flow is typically used for system-to-system communication. In this case, no user interaction is required, and the authentication is performed purely between technical components. This is the most common approach for backend integrations and automated processes.
 

Authorization Code Grant Type | BOC Developer Portal
The Authorization Code Flow is required if a real user context is needed. This is typically the case when working with Single Sign-On (SSO), where authentication is delegated to an Identity Provider. Only this flow enables proper user-based authentication in such scenarios.

OAuth 2.0 Authorization Code Grant Type Requirements

When using OAuth 2.0, the following user conditions must be met:

• Similar to Basic Authentication, the user involved must be a locally defined user and must not be linked to SSO. 

• This user must explicitly be configured as a technical user in the system settings.

• "Trusted Login" must be enabled.

• Configured Repository access.

When using OAuth 2.0, the following system conditions must be met:

The second part of the configuration is performed via the connector, where the OAuth client is created. During this process, the client ID and client secret are generated and later used to obtain access tokens: Authentication | ADONIS

Access to the API is then controlled via scopes, which define exactly which operations are permitted. This allows for a much more defined authorization model compared to Basic Authentication.

Please note: After configuration, an environment restart has to be triggered: Environment Restart Initiators
 

Recommendations

For productive environments, OAuth 2.0 should always be preferred due to its improved security model and flexibility.

Basic Authentication can still be useful for quick tests or initial setups, but it should not be considered a long-term solution in environments with higher security requirements.

Creating separate OAuth clients ensures a clear separation of access rights and simplifies maintenance. Changes can then be applied to a single integration without affecting others.