Authentication

Every request to the i4sea API is authenticated with an API key that belongs to your company.

Send the key in the Authorization header

GET /i4cast/v1/forecast/variables HTTP/1.1
Host: api.i4sea.com.br
Authorization: Bearer i4s_live_...

A key has the form i4s_live_ followed by 32 letters and digits. The header is the only place the API accepts it.

Never put the key in the URL

URLs end up in proxy logs, browser history and analytics tools. If a request carries a key, or anything that looks like one, in the query string (a parameter named api_key, apikey, key, token or access_token, in any letter case, or any value containing i4s_), the API rejects it with 400 key_in_query, even if the header is also present.

Treat a key that was sent in a URL as exposed and rotate it.

When the key is refused

A missing, malformed, unknown, revoked or expired key gets 401 unauthenticated. The API uses one code for all of these cases on purpose, so a response never reveals whether a key exists.

A valid key can still be refused with 403:

• insufficient_scope: the key was not granted the scope the endpoint requires.
• subscription_inactive: your company's API subscription is missing or suspended.
• product_not_in_plan: your plan does not include the endpoint's product.

Store the key safely

• Keep it in a secrets manager or an environment variable on your servers, never in source code or a repository.
• Call the API from your backend only. Do not ship the key in a browser or mobile app: anyone can read it there, and the API sends no CORS headers, so browsers block its responses anyway.
• Do not log request headers that contain it.
• i4sea stores only a one-way hash of each key and never shows a key again after creating it. If you lose a key, ask for a new one.

Use one key per system

Your company can hold several active keys. Using one per system or environment (for example, one for your production integration and one for a reporting job) lets you revoke one without stopping the others. All of your company's keys share its monthly quota; each key has its own per-minute limit (see Limits and quotas).

Rotate a key

Revocation is permanent: a revoked key cannot be reactivated. To rotate without downtime:

1. Ask i4sea for a new key with the same scopes.
2. Deploy the new key everywhere the old one is used.
3. Ask i4sea to revoke the old key. Within 10 seconds, every request with it gets 401.

If a key may have leaked, ask i4sea to revoke it first and deploy the replacement afterwards.

A key may also be created with an expiry date; after it, the key gets 401 like a revoked one.