How Do You Authenticate API Users in Drupal?

by

When building APIs in Drupal, one of the most important questions to answer is:

Who is calling the API?

This is where authentication comes in.

Drupal supports multiple authentication mechanisms, each designed for different use cases such as SPAs, mobile apps, internal services, or public APIs. In this blog, we’ll break them down clearly and help you choose the right one.

Authentication vs Authorization (Quick Reminder)

  • Authentication → Who are you?
  • Authorization → What are you allowed to do?

Even after authentication, Drupal permissions and roles still control access.

Cookie-Based Authentication (Session Authentication)

How It Works

  • Uses Drupal’s normal login system
  • Browser automatically sends the session cookie
  • Works out of the box with Drupal routes and JSON:API

When to Use

  1. Headless frontend on the same domain
  2. React / Vue SPA
  3. Admin dashboards

Example

User logs in via /user/login, and subsequent API calls automatically include the session cookie.

Advantages

  • Simple and secure
  • Uses Drupal’s native authentication
  • No token handling required

Disadvantages

  • Same-domain only
  • Not ideal for third-party clients

Basic Authentication

How It Works

  • Uses HTTP Authorization header
  • Sends username and password (Base64 encoded)

Example Header

Authorization: Basic dXNlcjpwYXNz

When to Use

  1. Simple integrations
  2. Server-to-server communication
  3. Internal APIs

Drupal 10 Setup

Enable required modules:

drush en basic_auth rest serialization -y

Advantages

  • Easy to implement
  • Widely supported

Disadvantages

  • Password sent with every request
  • HTTPS is mandatory
  • Not recommended for public APIs

OAuth 2.0 Authentication

How It Works

  • Uses access tokens instead of passwords
  • Tokens have limited scope and lifetime
  • Client exchanges credentials once, then uses token

When to Use

  1. Mobile applications
  2. Third-party integrations
  3. Public APIs

Drupal 10 Solution

  • Use Simple OAuth module
composer require drupal/simple_oauth
drush en simple_oauth -y

Advantages

  • Highly secure
  • Scalable
  • Tokens can be revoked

Disadvantages

  • More complex setup
  • Requires token management

JWT (JSON Web Token) Authentication

How It Works

  1. Client authenticates once
  2. Receives a signed JWT
  3. Sends token with each request

Example Header

Authorization: Bearer <jwt-token>

When to Use

  1. Single Page Applications (SPA)
  2. Mobile apps
  3. Stateless APIs

Drupal Setup

  • Use JWT module, often combined with OAuth

Advantages

  • Stateless
  • Fast
  • Works across domains

Disadvantages

  • Token revocation is harder
  • Requires careful expiration handling

API Keys (Custom Authentication)

How It Works

  • Client sends an API key in headers
  • Drupal validates the key manually

Example Header

X-API-KEY: your-api-key

When to Use

  1. Read-only APIs
  2. Internal tools
  3. Low-security data

Advantages

  • Very simple
  • Minimal setup

Disadvantages

  • Least secure
  • No user identity by default
  • No granular permissions

JSON:API Authentication (Special Case)

JSON:API does not provide authentication by itself.

It relies on:

  1. Cookie-based authentication
  2. Basic Authentication
  3. OAuth 2.0 / JWT

Important:
All Drupal permissions and access checks still apply normally.

Choosing the Right Authentication Method

Simple Decision Guide

  1. Same-domain frontend → Cookie-based authentication
  2. Internal services → Basic Authentication
  3. Mobile / third-party apps → OAuth 2.0
  4. Stateless APIs → JWT
  5. Simple read-only APIs → API keys

Best Practices for API Authentication

  1. Always use HTTPS
  2. Never expose user passwords
  3. Apply least-privilege permissions
  4. Use token expiration
  5. Log authentication and access events
  6. Revoke compromised tokens immediately

Summary

  • Drupal supports multiple API authentication methods
  • Authentication answers who you are
  • Authorization controls what you can access
  • JSON:API relies on Drupal’s authentication
  • The best method depends on the client type

Key Takeaways

Drupal supports cookie, basic auth, OAuth, JWT, and API keys
Authentication ≠ authorization
Permissions still control access
JSON:API uses Drupal authentication
Choose authentication based on security and client needs