Providing an overview of the authentication used for an API, with details of how API consumers can obtain the tokens and keys they need has become a common building block in the portals of leading public API providers. Don’t make API consumers look for authentication information, and make it as easy as possible to understand what is needed through examples and supporting tooling.
Authentication pages should be linked from getting started pages and be included as part of a wider security strategy page. Authentication should link to the JWT and OAuth standards used, and include scopes, examples, and tooling that help make it easier for consumers to authenticate. Don’t reinvent the wheel here and spend time looking at the approach of other API providers you depend on, and consider adopting leading authentication vendors to power your implementation.
After documentation, authentication is where API consumers most often get stuck and encounter friction when onboarding with APIs, as well as expanding their usage across different APIs. Keep your authentication standardized and well documented, and do the work for consumers whenever possible. Authentication is how we secure our digital resources and capabilities and ensure that bad actors do not gain access to the APIs made available to 1st-party, as well as partner and 3rd-party applications and integrations.