API Auth: Authentication Methods and Examples

API authentication ensures that only authorized systems or users can interact with your APIs. It involves setting up mechanisms to verify the identity of clients making requests to your API. By securing access to your API, you prevent unauthorized entities from exploiting your endpoints, which helps maintain your system's overall integrity and functionality. Robust API authentication also safeguards sensitive data from unauthorized users.

In this guide, you'll learn about the following common API authentication methods, the way they work, and their pros and cons:

• Basic auth
• API keys
• OAuth
• OpenID Connect (OIDC)
• Integration system user (ISU)
• Hash-based message authentication code (HMAC)
• Certificate signing request (CSR)

Basic Auth

This is the most straightforward authentication method. It requires the incoming request to include the username and password in the authentication header. The username and password combination can be sent as plaintext or a Base64-encoded string. The header typically takes the format Authorization: Basic <Base64EncodedCredentials>. When the API receives the request, it decodes the Base64-encoded string and verifies it against the records in the database. If the credentials are valid, the API grants access to its resources:

While this authentication method is easy to implement, it suffers significant drawbacks; for example, malicious attackers may be able to intercept the credentials and use them to perform man-in-the-middle attacks.

A good example of an API that uses basic auth is from UKG Pro, a powerful human capital management (HCM) suite designed to help organizations manage and enhance their workforce experiences.

Here is a sample request that uses basic auth to retrieve all employee deductions from the UKG Pro API:

curl --request GET \
 	--url https://hostname/personnel/v1/emp-deductions \
 	--header 'accept: application/json' \
 	--header 'authorization: Basic PFVTRVJOQU1FPjo8UEFTU1dPUkQ+'
	--header ‘US-Customer-Api-Key: ABCDE1’ \

Using basic authentication alongside an API key improves the security of the application by adding an extra layer of protection. This dual approach ensures that even if one credential, such as the API key, is compromised, unauthorized access is still prevented unless the attacker also has access to the corresponding username and password.

This method is best suited for simple internal tools where the authentication process needs to be quick and straightforward, like accessing internal dashboards or administrative panels.

API Keys

API keys are unique identifiers that authenticate requests and are typically generated from the API provider's dashboard. They are included in every request made to the API, either in the request headers or as query parameters. Upon receiving the request, the server validates the API keys and either grants or denies access to the API resources:

API keys are popular due to their ease of implementation and ability to be quickly revoked or regenerated if compromised or outdated. However, they are susceptible to interception if the connection is not encrypted since they are transmitted in plaintext. Also, while API keys can be configured with certain scopes or permissions, they lack the built-in fine-grained access controls that are found in more advanced methods like OAuth.

[Teamtailor](https://www.teamtailor.com/en/, an all-in-one recruitment software, is a good example of an API that uses API keys for authentication.

Here is a sample request to the Teamtailor API that uses an API key to retrieve lists of jobs:

curl --location 'https://api.teamtailor.com/v1/jobs' \
  --header 'Authorization: Token token=od71S1zmxWetVvzz6ovSeznEPb-OdsZZSX9EeBi9' \
  --header 'X-Api-Version: 20240404'

This method is best suited for simple integrations, such as public APIs, service-to-service communication, and internal applications.

OAuth

OAuth is an authorization protocol that allows the user to access API resources without giving the API access to their credentials, such as the username and password. This method typically involves three parties: the user (the resource owner), the client application (the application requesting access), and the authorization/resource server. OAuth supports several types of flows, including authorization code, proof key for code exchange (PKCE), client credentials, and more. Let's take a look at the steps involved in the authorization code flow:

1. The user initiates an access request from the client application.
2. The client application redirects the user to the authorization server with an authorization request that includes the client ID, redirect URI, and requested scopes.
3. The authorization server requests that the user grant the requested permissions to the client application.
4. Once the user consents, the authorization server redirects the user back to the client application with an authorization code using the client's redirect URI.
5. The client application sends the authorization code to the authorization server to exchange it for an access token.
6. The client application then uses the access token to make authenticated requests to the resource server and access the user's resources.

OAuth offers several advantages, such as enhanced security and fine-grained access control. However, the complexity of its implementation can be a major drawback as it involves several steps to authenticate the user.

A good example of an API that uses OAuth is from QuickBooks, an accounting software developed by Intuit.

Here is a sample request in the authorization code flow where the client application exchanges the authorization code for an access token from Intuit's authorization server.

curl -X POST 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=' \
-d 'grant_type=authorization_code' \
-d 'code=abc123' \
-d 'redirect_uri=https://yourapp.com/callback'

This method is ideal for third-party applications that need to access user data without exposing user credentials. It is commonly used in social media integrations, third-party applications accessing user data, and scenarios requiring delegated access.

OpenID Connect

OpenID Connect (OIDC) is an authentication protocol built on top of OAuth. As mentioned earlier, OAuth is an authorization protocol. OIDC adds an identity layer to it. OIDC involves the same parties as OAuth and follows almost the same steps as OAuth, with two key differences:

1. When the client application redirects the user to the authorization server, it must specify the scope as openid, along with other requested scopes.
2. When the client application sends the authorization code to the authorization server, it receives not only an access token but also an ID token. The ID token is a JSON Web Token (JWT) that contains information about the user in the form of claims.

OIDC offers several advantages, including simplified user authentication, enhanced security, and single sign-on (SSO) across different applications. However, since OIDC is an authentication method and not an authorization method, it cannot be used to make signed requests on behalf of the user to the provider site to perform create, read, update, and delete (CRUD) operations. Also, although OIDC is very secure, in rare cases where an attacker gains access to a user's OpenID credentials, they can access sensitive data across various sites where the user employs SSO.

An example of a popular API that uses OIDC is from Salesforce, a leading CRM software solutions provider.

In Salesforce, when using Okta as the OIDC provider, you can use the following sample code to make an authorization request. This returns an HTML page with a code that you can exchange for an access token and an ID token:

curl --location --request GET 'https://<OKTA-DOMAIN>/oauth2/v1/authorize?client_id=<CLIENT_ID>&response_type=code&response_mode=form_post&sessionToken=<SESSION_TOKEN>&redirect_uri=<REDIRECT_URI>&scope=openid groups&state=mystate&nonce=mynonce'

This method is best suited for applications that require user authentication and SSO across multiple domains.

Integration System User

An ISU is a dedicated user account that is created to enable programmatic access to APIs. This method typically involves creating a system user with predefined roles and permissions to perform the necessary actions. The credentials for this system user, which typically include a username and a password, are then used by applications to authenticate and authorize API requests:

Using this authentication method offers numerous advantages, such as dedicated and controlled access for programmatic interactions and clear audit trails for the activities performed by the service user. However, securely storing the system user credentials is a challenge, and if they are exposed, they can be used by malicious actors to access sensitive resources.

Several enterprise APIs use ISUs as the authentication method. A good example is from Workday, a leading provider of enterprise cloud applications for finance, HR, and planning.

Here is a sample request to the Workday API that retrieves worker data:

curl --location 'https://wd2-impl-services1.workday.com/ccx/service/{TENANT}/Human_Resources/v40.1' \
--header 'Content-Type: application/xml' \
--data '<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:bsvc="urn:com.workday/bsvc">
	<soapenv:Header>
    	<wsse:Security>
        	<wsse:UsernameToken>
            	<wsse:Username>{ISU_USERNAME}</wsse:Username>
            	<wsse:Password>{ISU_PASSWORD}</wsse:Password>
        	</wsse:UsernameToken>
    	</wsse:Security>
	</soapenv:Header>

	<soapenv:Body>
    	<bsvc:Get_Workers_Request/>
	</soapenv:Body>
</soapenv:Envelope>'

This method is best suited for system-to-system integrations within enterprise environments.

Hash-Based Message Authentication Code

HMAC is a message authentication mechanism that uses a cryptographic hash function and secret key, both known to the server and the client, to guarantee the authenticity and integrity of a message. This method involves the following steps:

1. The client generates a unique HMAC value from the message and the secret key using a secure cryptographic function, such as SHA-256.
2. The client sends the message along with the unique HMAC value to the server.
3. The server, upon receiving the message, uses the same secret key and cryptographic function to compute the HMAC of the message. If the computed HMAC is the same as the one received from the client, the server concludes that the message has not been tampered with. Otherwise, it means that the message was modified, which renders it unauthentic.

HMAC guarantees security as it relies on secure cryptographic hash functions. Even if a message in transit is intercepted by malicious actors, it cannot be modified without detection. However, both parties must ensure that the secret key is securely stored because if it is compromised, the integrity of the HMAC is also compromised.

An example of a popular API that uses HMAC is from NetSuite, a leading integrated cloud business software suite.

This method is best suited for verifying the integrity and authenticity of messages transmitted over insecure channels, such as securing webhook notifications sent from an e-commerce platform to a payment gateway.

Certificate Signing Request

A CSR is a message that is sent by an applicant to a certificate authority (CA) to apply for a digital identity certificate. The CSR typically includes information that is included in the digital identity certificate, such as a public key, common name, organization name, organizational unit, locality, state, and country. The following steps are typically followed to apply for the digital certificate:

1. The applicant generates a private and public key pair using tools such as OpenSSL. The private key is kept secret, while the public key is included in the CSR.
2. The applicant creates the CSR by including their information as well as the public key.
3. The CSR is submitted to the CA, which verifies the information provided, signs the CSR with its private key that creates the digital identity certificate, and issues it to the applicant.

The digital identity certificate can then be used for authentication and encryption of data transferred between a server and a client. Authentication can either be one-way or two-way.

One-way authentication uses the SSL technology, and only the server is authenticated. Here are the steps involved:

1. The client requests data from the API.
2. The API sends its digital identity certificate to the client.
3. The client verifies the API's certificate against a list of trusted CAs.
4. If the certificate is valid, a secure connection is established between the client and server.

Two-way authentication uses mutual SSL technology and allows the involved parties to authenticate with each other. Here is an overview of the steps involved:

1. The client requests data from the API.
2. The API sends its digital identity certificate to the client.
3. The client verifies the API's certificate against a list of trusted CAs. If the certificate is valid, the client sends its certificate to the API.
4. The API verifies the client's certificate against a list of trusted CAs. If everything checks out, secure communication is established between the two parties.

CSR-based authentication offers high security, especially with mutual authentication, which makes it very effective against man-in-the-middle attacks. It also provides a strong guarantee of both parties' identities. However, the initial setup can be complex as you need to generate, distribute, and install certificates. Ensuring proper storage of the certificates and handling revocation and expiration also adds to the overall complexity.

A good example of an API that uses CSR is from ADP Workforce Now, the all-in-one platform for payroll and HR software.

This method is best suited for high-security environments requiring mutual authentication, like establishing secure communications between a financial institution's servers and client applications.

Conclusion

In this guide, you learned about different API authentication methods, including API keys, basic auth, OAuth, OIDC, ISU, HMAC, and CSR. Each of these methods has its own weaknesses and strengths. Understanding these methods is important for implementing secure API integrations. By choosing the right method, you can ensure that the communication between your application and APIs is secure, which helps to maintain system integrity.

Apideck offers a comprehensive solution for managing API integrations with ease. With Apideck Vault, you can easily integrate and authenticate using any of the methods we have covered in this guide. By centralizing your API credentials and streamlining the authentication process, Apideck Vault simplifies the integration process, allowing you to focus on building and scaling your applications without worrying about the intricacies of managing multiple authentication mechanisms. Try Apideck today!