You have just created your Ulabase service. The APIs are ready and the database is empty. One question remains: how do you set up the first users and permissions?
Ulabase gives you two credentials for this: the root user and the Admin JWT, a token with administrator rights that lasts 15 minutes.
The Bootstrap Problem
Every secure application faces this problem. APIs require authentication, authentication requires users, and creating users requires API access. The usual solutions are awkward. Some systems disable security temporarily, and others ship with hardcoded initial admin credentials. Complex initialization scripts and manual changes to the database are common workarounds.
Ulabase solves it at creation time. Every service comes with a user called root. When you create the service, the console generates a strong password for root, sets it on the service and lets you copy it once.
The Admin JWT
Next to root's password, on the service's Home, is the Admin JWT. It gives you administrator access to that service for 15 minutes. Outside that service it gives no access at all: not to Ulabase, not to your other services.
What You Can Do
With the Admin JWT you can try a request by hand without typing root's password. Create users with their roles, add permissions, create collections, load seed data, and test your endpoints.
Using the Admin JWT
The Admin JWT works like any other JWT token:
curl -H "Authorization: Bearer <admin-jwt>" \
https://c0ffee.ulabase.app/users
Or in your code:
fetch('https://c0ffee.ulabase.app/users', {
headers: {
'Authorization': `Bearer ${adminJWT}`
}
})
Setting Up Your First Users
The typical flow takes a few minutes.
Step 1: Get Your Admin JWT
Open your service in the console. Its Home shows the Admin JWT.
Step 2: Create a User
curl -X POST \
-H "Authorization: Bearer <admin-jwt>" \
-H "Content-Type: application/json" \
-d '{
"_id": "alice",
"password": "her-password",
"roles": ["user"]
}' \
https://c0ffee.ulabase.app/users
Step 3: Give the Role a Permission
curl -X POST \
-H "Authorization: Bearer <admin-jwt>" \
-H "Content-Type: application/json" \
-d '{
"_id": "usersOwnOrders",
"roles": ["user"],
"predicate": "path-prefix('"'"'/orders'"'"') and method(GET)",
"priority": 100,
"mongo": {
"readFilter": { "owner": "@user._id" }
}
}' \
https://c0ffee.ulabase.app/acl
Step 4: Test the User
curl -u alice:her-password \
https://c0ffee.ulabase.app/orders
Alice now reads only the orders whose owner is alice.
The 15-Minute Window
The Admin JWT expires after 15 minutes, by design. The window is long enough for a test by hand, and short enough to limit the exposure if the token leaks. It also keeps you from relying on it for regular operations.
When it expires, click Refresh on the service's Home for a new one.
Security Best Practices
These guidelines keep your service secure while you work with the Admin JWT.
Do These Things
Use the Admin JWT right after you take it. Keep root's password in a password manager or a secure vault. Delete any test users you created once you have finished the setup. Take a fresh Admin JWT for each session and do not reuse old tokens.
Avoid These Mistakes
Never share an Admin JWT, even with team members. Never hard-code one in your application. Do not use it for regular application operations: your app signs in as one of the service's own users, with the roles you grant. An Admin JWT also cannot open a WebSocket change stream, which needs one of the service's users.
Beyond Initial Setup
The Admin JWT stays useful after the first setup, whenever you want to check something by hand.
If you lose root's password, set a new one in the Basic Auth box on the service's Home and click Reset password. If a permission you changed locks your app's users out, the Admin JWT still reaches the Permissions, so you can fix them.
Real-World Setup Example
A setup you want to repeat belongs in a script. The ulabase command line tool signs in to the service with an Admin JWT that it asks for itself, so the script needs no password. For a quick script of your own, this is the same setup with fetch:
const ADMIN_JWT = 'your-admin-jwt-from-the-home';
const API_BASE = 'https://c0ffee.ulabase.app';
async function initializeService() {
const headers = {
'Authorization': `Bearer ${ADMIN_JWT}`,
'Content-Type': 'application/json'
};
// 1. Create the orders collection
await fetch(`${API_BASE}/orders`, { method: 'PUT', headers });
// 2. Create a user
await fetch(`${API_BASE}/users`, {
method: 'POST',
headers,
body: JSON.stringify({
_id: 'alice',
password: 'her-password',
roles: ['user']
})
});
// 3. Let users read and write only their own orders
await fetch(`${API_BASE}/acl`, {
method: 'POST',
headers,
body: JSON.stringify({
_id: 'usersOwnOrders',
roles: ['user'],
predicate: "path-prefix('/orders') and (method(GET) or method(POST) or method(PATCH))",
priority: 100,
mongo: {
readFilter: { owner: '@user._id' },
writeFilter: { owner: '@user._id' },
mergeRequest: { owner: '@user._id' }
}
})
});
// 4. Seed initial data
await fetch(`${API_BASE}/orders`, {
method: 'POST',
headers,
body: JSON.stringify([
{ item: 'Initial order 1', owner: 'alice' },
{ item: 'Initial order 2', owner: 'alice' }
])
});
console.log('Service initialized successfully!');
}
initializeService();
Run this once, and your service is configured.
Complete Documentation
For detailed information about root user setup and security configuration:
Start Building
Creating your Ulabase service is free. Get your Admin JWT and set up your first user in minutes.
Build your app on Ulabase
Your backend is ready in minutes, and you spend your time on your app. The Free plan needs no credit card.