Authentication Means: Flexible, Secure, Ready

Authentication is critical, and choosing the right method depends on your use case. Building a web app? Mobile app? Integrating with third-party services? Each scenario has different needs.

RESTHeart Cloud supports multiple authentication methods out of the box, letting you choose the best approach for your application.

Three Ways to Authenticate

RESTHeart Cloud provides three authentication mechanisms, all working seamlessly together. Basic Authentication offers simplicity and universality, JWT Tokens provide modern stateless authentication, and Cookie-Based Auth delivers the perfect experience for web applications. Let's explore when and how to use each approach.

Basic Authentication: Universal and Simple

Basic authentication works everywhere - browsers, mobile apps, API clients, and command-line tools. Its universal compatibility makes it the go-to choice for testing, development, and server-to-server communication.

How It Works

Send credentials in the Authorization header using a simple curl command:

curl -u user@example.com:password \
  https://your-service.restheart.cloud/api/data
content_copy

Or in your JavaScript app:

fetch('https://your-service.restheart.cloud/api/data', {
  headers: {
    'Authorization': 'Basic ' + btoa('user@example.com:password')
  }
})
content_copy

When to Use Basic Auth

Basic Auth shines in several scenarios. It's perfect for testing and development when you need to quickly verify API functionality. Server-to-server communication benefits from its simplicity and reliability. API integrations and command-line tools appreciate its straightforward implementation. When building quick prototypes, Basic Auth gets you up and running without ceremony.

The JWT Upgrade

Here's where it gets interesting: when you authenticate with Basic Auth, the response includes a JWT token you can use for subsequent requests. This automatic upgrade gives you the best of both worlds.

# First request with Basic Auth
curl -i -u user@example.com:password \
  https://your-service.restheart.cloud/api/data

# Response includes:
# Auth-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
content_copy

Now use the JWT token for better performance:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://your-service.restheart.cloud/api/data
content_copy

JWT Authentication: Modern and Stateless

JSON Web Tokens (JWT) are the modern standard for API authentication. They're stateless, secure, and perfect for distributed systems.

Why JWT?

JWT tokens offer compelling advantages for modern applications. Their stateless nature means no server-side session storage is needed, eliminating database lookups and scaling concerns. They work effortlessly across multiple servers, making them ideal for distributed architectures. Each token is self-contained, including user identity and permissions, which means efficient authentication without constant database queries. The JWT standard is widely supported across platforms and languages, making integration straightforward regardless of your technology stack.

Using JWT Tokens

Once you have a token (from Basic Auth or login), using it is straightforward:

// In your frontend app
const token = localStorage.getItem('authToken');

fetch('https://your-service.restheart.cloud/api/data', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
content_copy

Token Lifecycle

Understanding the token lifecycle is important for security. Tokens expire after a configurable duration, ensuring compromised tokens have limited usefulness. When tokens expire, simply refresh them by authenticating again. Logging out is as simple as discarding the token client-side, with no server state to clean up.

Cookie-Based Authentication: Web App Ready

Building a traditional web application? Cookie-based auth provides the best user experience by leveraging the browser's built-in cookie handling.

How It Works

Add the set-auth-cookie query parameter to your login request:

// Login and set cookie
fetch('https://your-service.restheart.cloud/api/login?set-auth-cookie', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('user@example.com:password')
  }
})
content_copy

The response sets an HTTP-only cookie containing the JWT token. From now on, the browser automatically includes it in every request - no manual header management needed.

Benefits

Cookie-based authentication brings several advantages to web applications. The browser automatically handles token inclusion, eliminating the need for manual header management in every request. HTTP-only cookies prevent XSS attacks by keeping tokens inaccessible to JavaScript. The approach feels natural and user-friendly, matching how the web has worked for decades. Built-in CSRF protection features provide additional security layers without extra work.

Perfect For

This authentication method excels in browser-based environments. Single-page applications (SPAs) benefit from automatic authentication without complex state management. Server-rendered web apps get seamless session handling. Progressive web apps (PWAs) enjoy reliable authentication across online and offline states. Any browser-based interface gains improved security and user experience.

Choosing the Right Method

Basic Auth: Development & Testing

// Quick testing
fetch('/api/data', {
  headers: {
    'Authorization': 'Basic ' + btoa('user:pass')
  }
})
content_copy

JWT: Mobile & API Clients

// Mobile app or API integration
const token = await secureStorage.get('authToken');
fetch('/api/data', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
content_copy

Cookies: Web Applications

// SPA or web app - no auth headers needed
// Cookie is automatically included
fetch('/api/data')
content_copy

OAuth Integration

RESTHeart Cloud also supports OAuth authentication with Google and GitHub. Users can log in with their existing accounts, and you get a JWT token back that works with any of the methods above.

// After OAuth login redirect
// JWT token is available as cookie or in response
// Use it like any other JWT token
content_copy

Mix and Match

The beauty of RESTHeart Cloud's authentication system is its flexibility. You can use different methods for different parts of your application based on what makes sense for each use case. Your web frontend can use cookie-based authentication for a seamless user experience, while your mobile app uses JWT tokens for API access. Admin scripts can rely on Basic Auth for server management, and third-party integrations can use JWT tokens for security. All of these approaches work with the same user database, the same permissions, and the same security model.

Security Built In

Regardless of which method you use, security is paramount. Passwords are securely hashed using industry-standard algorithms. Tokens are signed and verified to prevent tampering. HTTPS is enforced in production environments to protect credentials in transit. Expiration and refresh mechanisms are handled automatically. Protection against common attacks like brute force, XSS, and CSRF is built into the platform.

Start Building

Authentication shouldn't slow you down. With RESTHeart Cloud, it's ready to use from the first minute. In your first minute, Basic Auth is working. By minute two, JWT tokens are flowing. Minute three brings cookies set for your web app. By minute five, OAuth integration is complete. No authentication library to choose. No security vulnerabilities to patch. No session storage to configure.

Learn More

For detailed API documentation and advanced configuration:

Authentication Documentation

Ready to Build?

Create a free RESTHeart Cloud service and start authenticating users immediately.

Start Building Now

---

RESTHeart Cloud: Authentication done right, ready from day one.