API import authentication — API key vs. username/password (token exchange)

When you set up an API import, the form asks you to pick an Authentication method. There are two options, and they map to different vendor styles. Picking the wrong one is the most common reason "my API doesn't work."

Option 1: API key (default)

Pick this when your vendor gave you a long static string — typically called an "API key", "access token", "bearer token", or "personal access token". You paste it into the API token field and the system sends it as a header on every request.

Use this when:

• The vendor's developer portal has a "Generate API key" or "Create token" button and the resulting string is what you copy
• The vendor's docs say "include this header: Authorization: Bearer <your-key>" or "X-API-Key: <your-key>"
• The credential does not change unless you rotate it manually
• Examples: Kamstrup READy, Schneider EcoStruxure (PAT mode), most modern SaaS APIs

Option 2: Username + password (token exchange)

Pick this when your vendor only gave you portal login credentials — the same username and password you use to log into their web UI. There is no separate API key. The system POSTs your credentials to the vendor's login endpoint, gets back a short-lived token, and uses that token for the actual data calls. The login is repeated when the token expires.

Use this when:

• The vendor's docs show a /login or /auth/token endpoint that accepts your portal credentials and returns a JWT or session token
• You don't see any "Generate API key" feature in the vendor portal
• The vendor uses a "login first, then call data endpoints" pattern
• Examples: GK Piscada Historian (POST /login with piscadaId + password → JWT)

What goes in each field

For "API key" mode:

• API URL: the base URL of the data endpoint (e.g., https://api.vendor.com/v1)
• API token: the long string from the vendor portal
• Username / Password: leave empty

For "Username + password" mode:

• API URL: the base URL of the API (the AI finds the /login endpoint from the OpenAPI spec you provide)
• API token: leave empty — it is ignored in this mode
• Username: your portal username
• Password: your portal password
• Login field names (advanced): only fill these in if the vendor uses non-standard body field names. Default is "username" and "password". GK Piscada uses "piscadaId" instead of "username", so you'd put piscadaId in the username field name override.

Why can't the AI fill in my credentials automatically?

The AI reads the vendor's OpenAPI / Swagger spec to discover where to authenticate and which fields the login endpoint expects. It cannot know your personal username, password, or API key — those are issued to you by the vendor and never appear in public documentation. You always paste those yourself.

How to tell which mode your vendor uses

1. Look at the vendor's API docs or developer portal
2. Search for "authentication" or "getting started"
3. If you see "create an API key" → API key mode
4. If you see "POST /login" or "OAuth password grant" with your portal username → Username + password mode
5. If unclear, ask the vendor support: "Does your API use a static API key, or do I authenticate with my portal login?"

Security note: Whichever mode you pick, your credentials are encrypted at rest and only decrypted in memory when the scheduler makes a fetch. They are never logged or exposed in error messages.