Programmatic authentication: API key, personal access token, and OAuth client credentials flow

Background

In software development, when we need to programmatically access API resource through CLI commands, or establish communication between backend services, there are usually three authentication mechanisms that are widely used by us developers: API key, Personal Access Token (PAT), and OAuth client credentials flow (branded as Machine-to-Machine in Logto). But what are the differences between them? What is the best fit scenario for each of these methods? In this blog post, we’ll delve into the similarities, differences, and provide insights into when to use each in different scenarios.

Definitions:

• API key: A simple string that can authenticate your request to an API resource.
• Personal Access Token (PAT): Also a simple string but represents a user when using it to authenticate to an API resource. It’s a delegation of a user.
• Logto Machine-to-Machine (Logto M2M): A standard OAuth client credential flow, which requires a client to be registered in prior, and requires using the client ID and secret to exchange for an access token. Thus, Logto M2M credential represents a trusted client and the nature of OAuth client credentials flow makes it relatively complicated when using it.

Similarities:

1. Authentication purpose:

• All three, API key, PAT, and Logto M2M, serve the primary purpose of authenticating a user or an application to access a specific service or resource. They act as credentials to prove the identity of the requester, and is usually used in CLI commands or backend-to-backend communication scenarios.

2. Security measures:

• All these three authentication methods should be handled with security in mind. Developers must ensure secure storage and transmission to prevent unauthorized access.

Differences:

1. User context:

• API key does not identify a principal, nor do it provide any authorization information. Therefore, the API keys are often used for accessing public data or resources anonymously. All services are NOT supported by the use of API keys.
• PAT is user identities and will represent you when it is used to request an API resource. In some systems, PATs are not allowed to access certain services. E.g. Publishing NuGet packages to Azure Artifacts feed.
• Logto M2M credentials can only be used by trusted clients. The client must be registered in prior in order to be authenticated. When using Logto M2M credentials, it represents the trusted client instead of the user whoever is using it.

2. Granularity of permissions:

• PAT and Logto M2M credentials usually offer more granular control over permissions compared to API key, allowing fine-grained control over what actions can be performed.

3. Token format

• API key and PAT are usually opaque type of strings, plain and simple.
• Access tokens that are issued through Logto M2M mechanism is usually in JWT format.

4. Authorization flow

• API key and PAT are system generated opaque strings, no authentication flows involved during the process. For example, you can call Google Cloud natural language API like this:

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

• Logto M2M is utilizing the standard OAuth 2.0 client credential flow. Each client has to obtain a pair of client ID and client secret in prior, with which the client can exchange for an access token later. The client then uses the access token to access API resource.

When to use each:

API key:

• Service-to-service communication: API keys are suitable for scenarios where applications need to communicate with APIs directly through CLIs. E.g. Calling OpenAI APIs.
• Public APIs: When exposing APIs to the public, API keys provide a straightforward method of access control.
• Simplified setup: For quick and simple authentication needs, especially in development phase. Unlike Logto M2M, API keys do not require client registration in prior, and do not need to exchange for an access token, either. You just pass your API key as a parameter in your request and it just simply works.

Personal Access Token (PAT):

• User-specific actions: When an application needs to perform actions on behalf of a user.
• Fine-grained access control (user): When precise control over the actions a user can perform is required.

Logto Machine-to-Machine (Logto M2M):

• Security: Logto M2M is ideal for scenarios where only trusted clients are allowed to access the backend services.
• Fine-grained access control (client): When precise control over the actions an application can perform is required.

Conclusion

In summary, the choice between API keys, PATs, and Logto M2M depends on the specific requirements of your application, whether it involves user-specific actions, machine-to-machine communication, or a combination of both. Assess the security and functionality needs to determine the most appropriate authentication method for your use case.

Logto M2M mechanism allows users to set granular access controls over RBAC (Role-based Access Control) feature. We are also planning to support API key and PAT in the near future. Please stay tuned to our feature updates!