ETERA API Documentation

Overview

ETERA uses JWT Bearer tokens for API authentication. Tokens are obtained through one of several authentication methods, then passed in the Authorization header on every request.

$ Authorization: Bearer YOUR_JWT_TOKEN

Choose Your Auth Method

Phone OTP

Email OTP

Google OAuth

Apple OAuth

Best for mobile apps. 3-step flow using SMS verification.

Send OTP

$ curl -X POST "https://api.etera.dev/auth/api/auth/phone-number/send-otp" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "phoneNumber": "589595029",
>     "countryCode": "+971"
>   }'

Verify OTP

$ curl -X POST "https://api.etera.dev/auth/api/auth/phone-number/verify" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "phoneNumber": "589595029",
>     "countryCode": "+971",
>     "code": "123456"
>   }'

Update Profile (new users)

$ curl -X PATCH "https://api.etera.dev/auth/api/auth/me" \
>   -H "Authorization: Bearer YOUR_JWT_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "firstName": "John", "lastName": "Doe", "language": "en" }'

Phone numbers use the number without country code in phoneNumber and the calling code with + prefix in countryCode. Example: UAE +971 58 959 5029 becomes phoneNumber: "589595029", countryCode: "+971".

Using Your Token

Once authenticated, include the JWT in all API requests:

$ curl "https://api.etera.dev/restaurant/search/recommendations/" \
>   -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Get Current User

Retrieve the authenticated user’s profile:

$ curl "https://api.etera.dev/auth/api/auth/me" \
>   -H "Authorization: Bearer YOUR_JWT_TOKEN"

Security Schemes

Bearer Auth (JWT)

Used by most client-facing endpoints. Obtained through any of the authentication flows above.

Service	Uses Bearer Auth
Auth
Account
Context
Notification

Admin Secret (API Key)

Used for admin-only operations. Passed as a header value.

Service	Uses Admin Secret
Context
AI

Rate Limits

Scope	Limit
Phone/Email OTP	5 requests/hour per number or email
Authentication endpoints	20 requests/minute per IP
Profile updates	10 requests/minute per user
General API	100 requests/minute per IP

JWT tokens are stateless — store them securely on the client. Never expose tokens in URLs, localStorage on shared devices, or version control.

Next Steps

Environments

Switch between dev, staging, and production

Error Handling

Handle authentication errors gracefully

Auth API Reference

Full endpoint list for the Auth service