The Admin JWT: Your First Steps Made Easy

You've just created your RESTHeart Cloud service. Your APIs are ready. Your database is waiting. But there's a classic chicken-and-egg problem: how do you set up the first user when there are no users yet?

The Admin JWT solves this elegantly - giving you temporary superuser access to bootstrap your application.

The Bootstrap Problem

Every secure application faces this challenge. APIs require authentication, authentication requires users, and creating users requires... API access? Traditional solutions are clunky. Some systems require temporary security disabling, others rely on hardcoded initial admin credentials. Complex initialization scripts and manual database manipulation are common workarounds, but none feel elegant.

RESTHeart Cloud gives you something better.

The Admin JWT: Temporary Superpower

From your RESTHeart Cloud dashboard, the process is simple. Navigate to your service, click the Connect tab, and copy the Admin JWT token. This token gives you complete access to your service for 15 minutes, with no restrictions and full administrative privileges.

What You Can Do

With the Admin JWT, you have time to accomplish everything needed for initial setup. Create your first user accounts with appropriate permissions. Set up initial permission rules that will govern access control. Configure collections for your application data. Load seed data to populate your database with initial content. Test your API endpoints to ensure everything works as expected. Most importantly, establish your root user who will have permanent administrative access.

Using the Admin JWT

The Admin JWT works like any other JWT token, making it simple to use:

curl -H "Authorization: Bearer <admin-jwt-token>" \
  https://your-service.restheart.cloud/api/users
content_copy

Or in your code:

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

Setting Up Your Root User

The typical flow is straightforward and takes just a few minutes to complete.

Step 1: Get Your Admin JWT

From the RESTHeart Cloud dashboard, navigate to your Service and open the Connect tab where your Admin JWT awaits.

Step 2: Create Your Root User

curl -X POST \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "_id": "admin@yourdomain.com",
    "password": "your-secure-password",
    "roles": ["admin"]
  }' \
  https://your-service.restheart.cloud/api/users
content_copy

Step 3: Set Up Admin Permissions

curl -X POST \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "predicate": "path-prefix[/api/]",
    "priority": 100,
    "mongo": {
      "readFilter": "{}",
      "writeFilter": "{}"
    }
  }' \
  https://your-service.restheart.cloud/api/acl
content_copy

Step 4: Test Your Root User

curl -u admin@yourdomain.com:your-secure-password \
  https://your-service.restheart.cloud/api/users
content_copy

Done! You now have permanent admin access through your root user.

The 15-Minute Window

The Admin JWT expires after 15 minutes, and this is by design for security. The time window is carefully chosen: it's long enough to complete your initial configuration comfortably, yet short enough to limit security exposure if the token is somehow compromised. This design forces best practices by preventing reliance on temporary admin access for regular operations.

If you need more time, simply generate a new Admin JWT from the dashboard. There's no limit on how many you can create, giving you flexibility while maintaining security.

Security Best Practices

Following these guidelines ensures your service remains secure while you work with the Admin JWT.

Do These Things

Use the Admin JWT immediately after creation while it's fresh and your security context is clear. Set up your root user right away, establishing permanent access before the token expires. Store your root credentials securely using a password manager or secure vault. Delete any test users created with the Admin JWT once you've finished initial setup. Generate a fresh Admin JWT for each setup session rather than reusing old tokens.

Avoid These Mistakes

Never share Admin JWT tokens with others, even team members. Hard-coding Admin JWT in your application creates a serious security vulnerability. Using Admin JWT for regular application operations defeats the purpose of proper authentication. Leaving Admin JWT tokens lying around after setup increases exposure risk. Relying on Admin JWT for production operations prevents proper access control and auditing.

Beyond Initial Setup

The Admin JWT isn't just for first-time setup. Use it whenever you need administrative access in special circumstances.

If you forget your admin password, generate a new Admin JWT and reset it. When you need to fix permissions that have locked you out, Admin JWT provides the access you need to modify ACLs. For emergency database access when regular authentication isn't working, Admin JWT gives you unrestricted access. During development, Admin JWT lets you bypass permissions while testing new features without modifying your permission rules.

Real-World Setup Example

Here's a complete initialization script that demonstrates the full power of the Admin JWT:

const ADMIN_JWT = 'your-admin-jwt-from-dashboard';
const API_BASE = 'https://your-service.restheart.cloud/api';

async function initializeService() {
  const headers = {
    'Authorization': `Bearer ${ADMIN_JWT}`,
    'Content-Type': 'application/json'
  };

  // 1. Create root admin user
  await fetch(`${API_BASE}/users`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      _id: 'admin@yourdomain.com',
      password: 'secure-password',
      roles: ['admin']
    })
  });

  // 2. Set up admin permissions
  await fetch(`${API_BASE}/acl`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      role: 'admin',
      predicate: 'path-prefix[/api/]',
      priority: 100,
      mongo: { readFilter: '{}', writeFilter: '{}' }
    })
  });

  // 3. Create regular user role permissions
  await fetch(`${API_BASE}/acl`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      role: 'user',
      predicate: 'path-prefix[/api/data]',
      priority: 50,
      mongo: {
        readFilter: '{"owner": "@user._id"}',
        writeFilter: '{"owner": "@user._id"}'
      }
    })
  });

  // 4. Seed initial data
  await fetch(`${API_BASE}/data`, {
    method: 'POST',
    headers,
    body: JSON.stringify([
      { name: 'Initial Data 1' },
      { name: 'Initial Data 2' }
    ])
  });

  console.log('Service initialized successfully!');
}

initializeService();
content_copy

Run this once, and your service is fully configured.

Complete Documentation

For detailed information about root user setup and security configuration:

Root User Setup Documentation

Start Building

Creating your RESTHeart Cloud service is free. Get your Admin JWT and have your first user set up in minutes.

Start Building Now

---

RESTHeart Cloud: Thoughtful developer experience in every detail.