Authentication
API authentication methods and security guide
Authentication
Learn about 01.software API authentication methods and security settings.
API Key Types
Client Key (Public)
- Used in the browser/client
- For read-only operations
- Used to identify the tenant
Secret Key (Private)
- Used only in server environments
- Enables all read/write operations
- Used for JWT token generation
Do not include the Secret Key in client code or add the NEXT_PUBLIC_ prefix.
Environment Variable Setup
.env.local
NEXT_PUBLIC_SOFTWARE_CLIENT_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SOFTWARE_SECRET_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxVercel
Go to Vercel Dashboard → Project Settings → Environment Variables and add the keys for each environment (Production, Preview, Development).
Docker
ENV NEXT_PUBLIC_SOFTWARE_CLIENT_KEY=your-client-key
ENV SOFTWARE_SECRET_KEY=your-secret-keyAuthentication Methods
SDK (Automatic)
When using the SDK, authentication is handled automatically.
// Browser Client - Auto-authenticated with Client Key
const client = createBrowserClient({
clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY!
})
// Server Client - JWT auto-generated with Secret Key
const serverClient = createServerClient({
clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY!,
secretKey: process.env.SOFTWARE_SECRET_KEY!
})JWT Token (Direct REST API Usage)
Obtain Token
curl -X POST "https://api.01.software/api/users/login" \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "password"}'{
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": { "id": "user_id", "email": "user@example.com", "role": "tenant-admin" },
"exp": 1736251200
}Use Token
curl "https://api.01.software/api/products" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."Refresh Token
Default expiration is 7 days.
curl -X POST "https://api.01.software/api/users/refresh-token" \
-H "Authorization: Bearer current_token"API Key Header (Server Only)
curl "https://api.01.software/api/products" \
-H "X-API-Key: your_secret_key_here"Cookie Method
When logging in from the browser, cookies are set automatically.
Cookie: payload-token=<jwt_token>Session Management
Check Current User
curl "https://api.01.software/api/users/me" \
-H "Authorization: Bearer $TOKEN"Logout
curl -X POST "https://api.01.software/api/users/logout" \
-H "Authorization: Bearer $TOKEN"SDK JWT Utilities
For cases where you need to manage JWTs directly on the server:
import { createServerToken, verifyServerToken, decodeServerToken } from '@01.software/sdk/auth'
// Create JWT
const token = createServerToken({ userId: 'user-id' }, secretKey)
// Verify + decode JWT
const payload = verifyServerToken(token, secretKey)
// Decode JWT only (without verification)
const decoded = decodeServerToken(token)SDK API Key Utilities
import { createApiKey, parseApiKey } from '@01.software/sdk/auth'
// Create API Key (Base64 encoded)
const apiKey = createApiKey(clientKey, secretKey)
// Parse API Key (Base64 decoded)
const { clientKey, secretKey } = parseApiKey(apiKey)Permissions
| Operation | Browser Client | Server Client |
|---|---|---|
| Read (find, findById) | O | O |
| Write (create, update, remove) | X | O |
| Orders/Payment API | X | O |
Security Best Practices
- Manage keys with environment variables
- Use Secret Key only on the server
- Rotate keys regularly
- Never commit Secret Key to Git
- Use HTTPS in production
- Store tokens in HttpOnly cookies (prevents XSS)
Issuing API Keys
- Log in to the 01.software Console
- Navigate to tenant settings
- Issue a new key in the API Keys section
Next Steps
- Collections - Available collections
- Error Handling - Handling authentication errors
- REST API - REST API reference