Authentication
The Local Universe API supports two authentication methods: Bearer tokens for user sessions and Service tokens for bot/application access. All authenticated requests require an Authorization header.
Bearer Token (User Auth)
Bearer tokens are obtained through the OTP (one-time password) login flow. This is the standard authentication method for end users.
Login flow
Step 1: Request an OTP code by sending the user's email to the login endpoint. A verification code will be sent to their email.
Request
curl -X POST https://api.localuniverse.io/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com"}'
Response
{
"message": "Verification code sent"
}
Step 2: Verify the OTP code to receive an access token. The response includes the token and the authenticated user object.
Request
curl -X POST https://api.localuniverse.io/v1/auth/verify \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "code": "123456"}'
Response
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "1344387816333352652",
"username": "tino",
"email": "user@example.com",
"verified": true
}
}
Step 3: Use the access token in subsequent requests by passing it in the Authorization header as a Bearer token.
Authenticated request
curl https://api.localuniverse.io/v1/users/@me \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Logout
Invalidate the current session by calling the logout endpoint.
Request
curl -X POST https://api.localuniverse.io/v1/auth/logout \
-H "Authorization: Bearer {token}"
Service Token (Bot Auth)
Service tokens authenticate applications and bots. When you create an Application, you receive an api_key and api_secret. These are combined in the Authorization header.
Pass the Service token as Service {api_key}:{api_secret}.
Service token request
curl https://api.localuniverse.io/v1/systems/discoverable \
-H "Authorization: Service abc123:secret456"
Token format summary
| Method | Header format | Use case |
|---|---|---|
| Bearer | Authorization: Bearer {access_token} | User sessions (OTP login) |
| Service | Authorization: Service {api_key}:{api_secret} | Bots and applications |
Always keep your tokens safe. If you suspect a service token has been compromised, you can reset it via the Applications API using the reset bot token endpoint.