Set up authentication
Every ingest request requires an ingest connection API key. A connection represents a data provider sending data on behalf of a customer.
There is one API key per connection (customer + data provider). The key is not scoped to an asset or a data type. Use the same connection's key when sending different assets or data types for that customer, but never reuse it for another customer or data provider.
Choose the right connection
The connection model is the same whether you send your own data or provide data for someone else:
| Your integration | Which key to use |
|---|---|
| Sending on your own behalf | You are both the customer and the data provider. Typically, you need one connection and one API key per environment. |
| Providing data for multiple customers | You are the data provider for each customer. You need a separate connection and API key for each customer in each environment. |
For example, a provider sending for customers A and B must use A's connection key for A's data and B's connection key for B's data. Adding another ship for A does not require a new key.
Obtain a key
Contact your DNV representative with the customer, data provider, and target environment (customer test or production). You do not need to supply asset IDs or data types to obtain the connection's key.
API keys must be stored securely. See Store and select customer keys.
Credentials are environment-specific. A customer-test URL requires a customer-test key; use the corresponding production key when calling production.
Store and select customer keys
If you serve multiple customers, maintain a secure mapping from each customer's connection and environment to its API key. Before every send, select the key for the customer whose data you are sending. Do not configure one shared key for all customers or fall back to another customer's key when a credential is missing.
Store keys in your deployment's secret store and load the appropriate key at runtime. Do not put keys in source control, URLs, browser code, or request logs.
Authenticate requests
For HTTPS, send the key in the authorization header:
Authorization: ApiKey <your-ingest-api-key>
Other credential types are not accepted by the ingest API. For MQTT, use the same ingest key as the password; see MQTT configuration.
Configure an interactive HTTP client
For the Bash and curl examples, set the customer-test URL and the key for the specific customer + data provider connection used for this request:
export VISTA_GATEWAY_URL='https://vista-gateway-customer-test-api.dnv.com'
export VISTA_GATEWAY_API_KEY='<customer-test-api-key-for-this-connection>'
This selects customer test. For production, use the
production URL
and the key issued for that environment. The examples require curl 7.76 or newer
for --fail-with-body.
The variable holds only the key selected for this example, not a key to share
across customers. For deployed senders, select it from your secure customer-key
storage instead. Treat shell history containing real keys as sensitive, and do
not enable shell tracing (set -x) or verbose HTTP logging with credentials.
Rotate a key
Ask your DNV representative to coordinate rotation. Rotation changes the credential, not the ingest connection identity, so it does not require re-onboarding your data integration.
Update your sending system's secret and confirm it can authenticate with the new key. Coordinate the cutover rather than assuming the old and new credentials remain valid at the same time.