Mobula supports two ways to authenticate: a static API key (from the dashboard) and short-lived API tokens (JWTs you create from that key). This guide explains the difference and shows examples for both.
Comparison
| API Key | API Token (short-lived) |
|---|
| What it is | Long-lived credential from admin.mobula.io. Same value until you rotate or delete it. | JWT created via POST /api/2/auth/tokens. Expires after a set time and has an optional request limit. |
| How to send | Authorization: YOUR_API_KEY or x-api-key: YOUR_API_KEY | Only Authorization: Bearer <token> (do not use x-api-key) |
| Use case | Backend services, scripts, your own servers. Full control over the key. | Temporary access for a client (e.g. frontend, worker, partner). Limited lifetime and optional request cap. |
| Can create tokens? | Yes. Use the API key to call /api/2/auth/tokens and create tokens. | No. Short-lived tokens cannot create or manage other tokens. |
| Plans | All plans (free and paid). | Startup, Growth, Enterprise only. |
When to use an API key
Use your API key when:
- You call the API from a backend you control (server, cron job, script).
- You want one credential that does not expire (until you rotate it).
- You need to create or revoke short-lived tokens (token management requires the API key).
Example: request with API key
You can send the key in the Authorization header or in x-api-key:
# Option 1: Authorization header
curl -X GET "https://api.mobula.io/api/1/market/data?asset=bitcoin" \
-H "Authorization: YOUR_API_KEY"
# Option 2: x-api-key header
curl -X GET "https://api.mobula.io/api/1/market/data?asset=bitcoin" \
-H "x-api-key: YOUR_API_KEY"
When to use an API token (short-lived)
Use a short-lived API token when:
- You need to give a client (e.g. frontend, mobile app, partner service) access without sharing your main API key.
- You want a credential that expires and optionally has a request limit.
- You issue tokens from your backend and the client only holds the token.
Always use Bearer. Send the short-lived token only as Authorization: Bearer <token>. Do not send it in x-api-key.
Example: create a token, then call the API with it
Step 1 — Create a token (with your API key):
curl -X POST "https://api.mobula.io/api/2/auth/tokens" \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expiresIn": 3600000, "requestLimit": "1000"}'
token (JWT). Store it securely; it is returned only once.
Step 2 — Call any endpoint with the token (Bearer only):
curl -X GET "https://api.mobula.io/api/1/market/data?asset=bitcoin" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Summary
- API key: Long-lived, from the dashboard. Use
Authorization: YOUR_API_KEY or x-api-key: YOUR_API_KEY. Use it on the server and for creating tokens.
- API token: Short-lived JWT from
/api/2/auth/tokens. Use only Authorization: Bearer <token>. Use it for clients that should not see your API key.
