Authentication
Authentication is the process of verifying the identity of a user or application. It is a critical aspect of security and privacy, ensuring that only authorized users or applications can access protected resources. Oneloop provides a flexible and secure authentication mechanism that allows you to control access to your APIs and services.
Adding Authorization Header
Always prioritize security while balancing practical considerations for your specific use case.
When building your API endpoints, you should require clients to include an Authorization
header in their requests. The Authorization
header should contain a valid API key that is used to authenticate the request. There are 2 ways to include the Authorization
header in your requests:
API Authentication Methods
Bearer Token with HTTPS (Recommended)
The Bearer token method, used over HTTPS, is generally recommended for most modern API implementations. Here’s why:
- Simplicity: It’s straightforward to implement and use.
- Flexibility: It works well with various token types, including JWT (JSON Web Tokens).
- Security: When used over HTTPS, it provides strong protection against token interception.
- Statelessness: It supports stateless authentication, which is beneficial for scalable systems.
- Standard Compliance: It follows the OAuth 2.0 specification, making it widely recognized and supported.
- Some APIs utilize the
Authorization
header with the Bearer keyword to handle API keys. This method is also common for other tokens, such as those generated by OAuth.
Example usage:
GET /resource HTTP/1.1
Host: example.com
Authorization: Bearer your-api-key-here
When making requests to protected resources, the client must include this token in the Authorization
header.
X-API-Key Header
The x-api-key
header is a popular custom header for passing API keys, widely used due to its adoption by AWS API Gateway.
Example usage:
GET / HTTP/1.1
Host: example.com
X-API-KEY: abcdef12345
Basic Authentication
Basic Authentication can be used alongside or as an alternative to API keys. The API key can be passed as either the username or password, with the unused field typically left blank.
Example usage:
GET / HTTP/1.1
Host: example.com
Authorization: Basic bWFnZ2llOnN1bW1lcnM=
Note: The username:password
content needs to be base64-encoded. Most request libraries handle this encoding automatically.
Validating API Keys
Every request made to your API endpoints should be authenticated using an API key. Oneloop provides a built-in mechanism to validate API keys. When a request is made to your API, you can use the Oneloop SDK to verify the API key and ensure that it is valid and authorized to access the requested resource.
API Key Status
Whenever you validate an API Key with Oneloop, we also provide the status of the API Key. The status can be one of the following:
Active
: The API Key is valid and authorized to access the requested resource.Inactive
: The API Key has been deactivated and is no longer authorized to access the requested resource.Expired
: The API Key has expired and is no longer authorized to access the requested resource.Rate Limited
: The API Key has exceeded the rate limit and is temporarily blocked from accessing the requested resource.Usage Limited
: The API Key has exceeded the usage limit and is temporarily blocked from accessing the requested resource.Invalid Scopes
: The API Key does not have the required scopes to access the requested resource.Invalid
: The API Key is invalid and cannot be used to access the requested resource.