API Key Authentication
Finance API uses API key authentication. Every request must include a valid key in the F-API-KEY header.
| Header | Example |
|---|---|
F-API-KEY | F-API-KEY: fk-xxxxx |
Creating an API Key
- Log in to the Admin Dashboard.
- Navigate to the API Keys page.
- Click Create Key and configure:
- Name — A descriptive label for the key.
- Daily Quota — Maximum requests per day (default:
1000). - Monthly Quota — Maximum requests per month (default:
10000). - Expires At — Optional expiration date.
- Copy the key immediately. The full key is shown only once.
Using an API Key
Include the key in the request header:
curl -H "F-API-KEY: fk-xxxxx" \ "https://finance-api.xp-java.workers.dev/api/v1/etf/basic?code=510300"Key Security
- Treat your API keys like passwords. Do not expose them in client-side code.
- Do not commit keys to version control.
- Rotate or revoke compromised keys immediately from the dashboard.
- Keys are stored as SHA-256 hashes; the full value is never retrievable after creation.
Error Responses
Authentication errors return a JSON body with a non-zero code:
| HTTP | Code | Message | Cause |
|---|---|---|---|
| 401 | 4010 | Missing header | F-API-KEY header is absent |
| 401 | 4010 | Invalid header format | Bearer prefix required but missing (legacy mode) |
| 401 | 4011 | Invalid API key format | Key is too short or empty |
| 401 | 4012 | Invalid API key | Key does not exist in the database |
| 401 | 4013 | API key expired | Key has passed its expires_at date |
Example error response:
{ "code": 4012, "message": "Invalid API key"}