The Aero API uses JWT (JSON Web Token) bearer authentication to secure endpoints. Most endpoints require a valid JWT token in the request headers.
Authentication flow
Register or login
Create a new account or login with existing credentials to receive a JWT token
Include token in requests
Add the JWT token to the Authorization header in all authenticated requests
Token verification
The API verifies the token on each request and extracts user information
Registering a new user
Create a new user account by sending a POST request to the registration endpoint:
curl -X POST http://localhost:3000/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "your-secure-password",
"name": "John Doe"
}'
Request body
| Field | Type | Required | Description |
|---|
email | string | Yes | User’s email address |
password | string | Yes | User’s password (will be hashed with Argon2) |
name | string | Yes | User’s full name |
Response
On successful registration, you’ll receive a JWT token and user information:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "user_abc123xyz",
"email": "[email protected]",
"name": "John Doe"
}
}
Passwords are securely hashed using Argon2 before storage. User IDs are generated using CUID2 with a user_ prefix.
Error responses
| Status Code | Description |
|---|
409 | Email address is already in use |
500 | Internal server error |
Logging in
Authenticate with existing credentials:
curl -X POST http://localhost:3000/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "your-secure-password"
}'
Request body
| Field | Type | Required | Description |
|---|
email | string | Yes | User’s email address (case-insensitive) |
password | string | Yes | User’s password |
Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "user_abc123xyz",
"email": "[email protected]",
"name": "John Doe"
}
}
Error responses
| Status Code | Description |
|---|
401 | Incorrect password |
404 | No user found with given email |
500 | Internal server error |
Using the JWT token
Once you have a JWT token, include it in the Authorization header of your requests using the Bearer scheme:
curl -X GET http://localhost:3000/v1/auth/@me \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Bearer followed by the JWT token:
Authorization: Bearer <your-jwt-token>
Always keep your JWT token secure. Never expose it in client-side code or commit it to version control. Treat it like a password.
Token structure
The JWT token contains a payload with the user ID:
{
"id": "user_abc123xyz"
}
JWT_SECRET).
Getting current user
Verify your authentication and retrieve current user information:
curl -X GET http://localhost:3000/v1/auth/@me \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Response
{
"name": "John Doe",
"id": "user_abc123xyz"
}
Error responses
| Status Code | Description |
|---|
401 | Invalid or expired token |
404 | User not found |
500 | Internal server error |
Protected endpoints
Most API endpoints require authentication. The OpenAPI specification indicates protected endpoints with the following security schemes:
- JWT-auth: Bearer token authentication for all authenticated endpoints
- bearer: Alternative bearer token scheme used by some endpoints
Endpoints that require authentication will return 401 Unauthorized if no valid token is provided.
Code examples
// Register a new user
const registerResponse = await fetch('http://localhost:3000/v1/auth/register', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
email: '[email protected]',
password: 'secure-password',
name: 'John Doe'
})
});
const { token, user } = await registerResponse.json();
// Use the token for authenticated requests
const flightsResponse = await fetch('http://localhost:3000/v1/flights/tracked', {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`
}
});
const flights = await flightsResponse.json();
Security considerations
Use HTTPS in production
Always use HTTPS in production environments to encrypt token transmission
Store tokens securely
Store JWT tokens in secure storage (e.g., httpOnly cookies, secure local storage)
Set JWT_SECRET
Configure a strong, random JWT_SECRET environment variable for token signing
Implement token refresh
Consider implementing token refresh mechanisms for long-lived sessions
Environment configuration
Ensure the following environment variable is set:
JWT_SECRET=your-secure-random-secret-key
Never commit your JWT_SECRET to version control. Use a strong, randomly generated secret in production.