[ADP-363] Custom HTTP Authorization Schema

reviewing phase 1

Needs more reference

Overview

While Bearer tokens are commonly used for authorization, API designers MAY create custom authorization schemas to meet specific requirements. This specification describes how to design and implement custom authorization schemas.

Guidance

When implementing a custom authorization schema:

• Implementers MUST clearly document the format and usage of the custom schema.
• Clients MUST include the custom authorization header in all authenticated requests.
• Servers MUST validate the custom authorization header and return appropriate error responses for invalid credentials.
• All parties SHOULD transmit authorization information only over secure channels (e.g., HTTPS).
• SHOULD register the custom authorization scheme on the internal API portal, similar to IANA.

Custom Authorization Schema Example

A custom authorization schema might extend the standard Bearer token approach:

Authorization: CUSTOM-AUTH <token>

This method allows for explicit identification of a specific authorization type.

Design Recommendations

1. Designers SHOULD choose a clear, unique prefix (e.g., "CUSTOM-AUTH").
2. The schema name MUST NOT conflict with existing standards.

Custom Schema vs Standard Schemas

While custom schemas offer flexibility, they SHOULD be weighed against the benefits of using standard schemas:

1. Interoperability: Standard schemas are widely supported by existing tools and libraries.
2. Security: Well-established schemas have undergone extensive security review.
3. Developer familiarity: Standard schemas reduce the learning curve for API consumers.

API designers SHOULD use custom schemas only when standard options cannot meet specific requirements, such as:

• Unique identification needs
• Integration of proprietary authentication systems
• Specific compliance or regulatory requirements

References

• RFC 9110, Section 11.6.2 - Authorization
• IANA HTTP Authentication Scheme Registry