Developer Documentation

Programmatic Access lets your application request and receive vehicle data — historical, last-known, and real-time — directly from our APIs under the EU Data Act (EUDA). You register an integration once, receive credentials, and then call the data-request APIs to create requests, track their status, and retrieve delivered data.

Three things are true of every integration, and they shape everything else in this guide:

• Access is read-only. The B2B integration realm is a zero-trust, read-only environment. You can request data about a vehicle; you cannot send commands to a vehicle (no door unlock, no engine start). Those capabilities live in a separate fleet realm and are not exposed here.
• The vehicle owner is always in control. Data only flows after the owner has explicitly consented to the specific data you asked for, for the specific purpose you stated. You initiate; the owner approves. There is no path that bypasses owner consent.
• The platform meters and bills automatically. Pricing, payment, and invoicing are enforced by the platform before any backend service runs. Your backend never handles pricing logic — you register a payment method and the platform does the rest.

If you have integrated with OAuth providers or other consent-gated data APIs before, the overall shape will feel familiar. The one concept that is easy to under-estimate — and the one that causes the most integration bugs — is consent as a first-class, owner-controlled lifecycle that is independent of your access tokens. The Consent section is the most important in this guide; read it before you write code.

There are three actors:

Every request follows the same arc, regardless of integration model or data family:

The request does not return data synchronously at creation time. Creating a request returns a requestId and a status. You then either poll the status or subscribe to a webhook to learn when consent is granted and data is ready. Only when the request reaches APPROVED with consent GRANTED does data become retrievable.

Consent is owner-granted, scope-specific, time-bounded, revocable, and independent of your tokens. Internalize these five properties and most lifecycle questions answer themselves.

You initiate; the owner approves

For security and EUDA/GDPR compliance, the act of granting consent always happens in the owner's own secure portal session — never through your credentials. A B2B partner can initiate a consent request via API, but cannot grant it. How the owner is brought into the loop differs by integration model:

• M2M (server-to-server): When you create a request, the platform emails the owner a secure deep-link. They follow it, authenticate, review exactly what you asked for (data, purpose, time range), and approve or deny.
• App (Authorization Code + PKCE):The owner is redirected to the Nissan login + consent screen inline during your app's authorization flow, approves there, and is redirected back to your app.

Either way, the owner sees a plain-language description of your request — for example, "Allow [App Name] to access your driving-style data to provide a personalized insurance quote."

Scope-specific and additive-only

Consent is granted at the package level (see Data families). A grant covers exactly the packages and purpose you requested — nothing more. You cannot silently widen scope. If you later need data attributes that were not in the original grant, you must create a new request for the additional scope, which the owner approves separately. This enforces data minimization.

Time-bounded

Every grant carries a duration. Historical requests are bounded by a date range; subscriptions run for an agreed term. When the term ends, consent reaches a terminal "expired" state and data stops automatically.

Revocable at any time

The owner can revoke an active consent from their portal at any moment. Revocation is immediate: real-time streams associated with that grant are terminated and no further data flows. Your integration must treat revocation as a normal, expected event — not an error — and stop relying on that data.

Independent of your access tokens

This is the property most likely to bite you. Your OAuth/M2M token lifecycle and the consent lifecycle are two separate things.

• A valid, unexpired access token does not mean you are entitled to data. Entitlement is gated by stored consent, evaluated fresh on every data access.
• Conversely, refreshing or re-minting a token does not re-grant or extend consent.

So: a real-time read can return 403/no-data even with a perfectly valid token, because the owner revoked consent or the term expired. Always check the request/consent status, not just your token, before assuming data is available.

Consent request expiry

If the owner never acts on a pending request, the request expires after a configurable window (commonly ~7 days, with reminders) and the secure link becomes invalid. The opportunity is closed and you must initiate a fresh request. You are notified of expiry via webhook/polling like any other status change.

Before any data is read, every request passes through a centralized compliance engine — three sequential gates. If any gate fails, the request is terminated immediately. You don't call these gates; they run for you. Knowing they exist explains why a request can be rejected even when your call is well-formed.

Gate 3 is why a historical request can succeed but return less data than the full date range you asked for: only the portion of the window during which the consenting owner actually owned the vehicle is eligible.

Every service package belongs to one of three families. The family determines the delivery mechanism, the request endpoint, and the billing model. List the packages available to your account before creating a request (see the service-package catalog); use the returned package id values in your request body.

Notes that matter in practice:

• Data availability is vehicle-dependent. For retrieving recorded values, a given vehicle supports either the Historical (time-series over a date range) option or the Last Known Value option — not necessarily both. Some vehicle models expose only the last-known-value service. Always rely on the service-package catalog and the package type to see what is actually available for your account and the vehicles you query, rather than assuming a vehicle supports historical.
• Real-time delivery is event-driven, not a raw firehose. Subscriptions surface meaningful events — e.g., journey completed, charge-state changed, safety fault — rather than continuous raw pings. This protects your receiving infrastructure. Pull reads give you the latest known state on demand.
• A resource can legitimately return no dataif the vehicle doesn't support it. For example, the charging resource returns 404 for non-EV (ICE) vehicles.
• Very high-volume continuous telemetry is out of scope here. Webhook-based delivery is designed for self-serve SME-to-mid scale. If your run-rate or frequency needs grow past the threshold for managed streaming, that is a managed high-throughput streaming tier conversation — contact your account team rather than working around webhook limits.

Billing is enforced by the platform, not your backend. The model depends entirely on the data family / request type — not on whether the call came from an M2M backend or an app.

The prerequisite: a valid payment method

Your API credentials remain suspended until your B2B account has a complete billing profile and a valid default payment method (a credit or debit card). Until then, data-request calls are blocked. Add a payment method in account settings to activate.

Pricing tier

Pricing is rendered dynamically by account type:

• SME — EUDA margin-free rate.
• Large Enterprise — commercial rate.

You don't pass a price; the platform computes it from your account type and the requested package.

Workflow A — One-off historical & last-known (strict prepaid)

A pre-authorization hold is placed for the exact price when the request is created. Payment is captured only at the moment consent is granted; if the owner never consents, the hold is released and nothing is charged.

Workflow B — Recurring subscriptions (periodic & real-time, postpaid aggregated)

Because consented VINs can be added or revoked organically throughout the month, individual VINs are not charged per transaction. Instead, on the 1st of each month, an aggregated billing job sums all active, consented VINs for your account over the prior month and raises a single consolidated charge.

Invoices & retention

Invoices are generated at capture (Workflow A) or at the monthly aggregation (Workflow B) and are available in the portal. Financial records are retained for tax-compliance purposes independently of account deletion.

You pick the authorization model when you create the integration, and it cannot be changed afterwards. If you need both, create two integrations.

Rule of thumb: if a human owner is present in your UX and you want them to authenticate and consent in the moment, use App (PKCE). If you're running unattended backend jobs against VINs your organization is permitted to act for, use M2M and rely on email-link consent capture. Both share the same package catalog, the same data-request lifecycle, and the same billing model.

Make sure the following are in place for your B2B account. Data requests are blocked until every gate below passes.

• An active B2B account (not suspended), and your organization is not on a sanctions/gatekeeper blocklist (Gate 1).
• A complete billing profile with a valid default payment method (a credit or debit card). Until this exists, your API credentials are suspended.
• Accepted platform terms and Data Terms & Conditions.

Development vs. production: a development account is sandboxed and vehicle-count-limited for PoC and pre-prod validation; a primary account runs live, contracted services. Build and validate against development first.

From the Programmatic Access tab, choose Create Integration and complete the form:

• Application name (3–50 characters).
• Authorization model — M2M or Authorization Code. Immutable after creation.
• Redirect URLs — required for Authorization Code. These are the only URLs the authorize step will redirect back to (exact match).
• Purpose of the integration (shown to owners in the consent prompt).
• Service packages you intend to request.
• Accept the Data Terms & Conditions.

Submit to register. You can later update most fields, but the authorization model stays fixed.

Your credentials

After creation, credentials are shown once in a popup. Store them securely before closing it (you can also download a PDF summary).

• M2M: a client_id and a client_secret (the secret is shown only once).
• Authorization Code: a client_id only (no secret — security comes from PKCE).

A service package defines the data a request can access, and which family/billing it falls under. List what's available to your account before creating a request:

M2M

GET {API_BASE}/cms/m2m/accounts/{account_id}/service-packages?dataType=HISTORICAL|REAL_TIME

App (PKCE) — same shape, OAuth path + dual-token headers:

GET {API_BASE}/cms/oauth/accounts/{account_id}/service-packages?dataType=HISTORICAL|REAL_TIME

Each package returns at least an id, name, description, and type. Use the package id values in the packages array when you create a data request. The catalog is the source of truth for what a given vehicle/account supports — including whether historical time-series or only last-known-value reads are available (see Data families).

Backend service, no interactive login. Consent is captured via an emailed secure link to the owner.

1. Your backend → Platform API: POST /cms/m2m/token (client credentials)
2. Platform API → Your backend: access_token
3. Your backend → Platform API: POST data-request (VIN, package, owner email)
4. Platform API → Vehicle owner: Email secure consent link
5. Platform API → Your backend: requestId, status = PENDING
6. Vehicle owner → Platform API: Approve in secure portal
7. Platform API → Your backend: Webhook CONSENT_GRANTED (or poll status)
8. Your backend → Platform API: GET data (deliveries / resource)
9. Platform API → Your backend: Pre-signed download URL or JSON

Step 1 — Get an access token

Exchange your account ID and client credentials for a bearer token:

curl -X POST "{API_BASE}/cms/m2m/token" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

The response contains an access_token and its expires_in lifetime. Send it on every subsequent call:

Authorization: Bearer <access_token>

Step 2 — Create a data request

Use the endpoint that matches the package family:

A request identifies a vehicle (17-character vin), the vehicle user's email (used to notify the owner for consent), and one or more package id values. Historical requests also take requestType (ONE_OFF or PERIODIC), a date range, and — for periodic — a frequency. The exact field names and validation rules are in the API reference.

What happens behind the scenes: the platform runs synchronous validations (valid VIN, resolvable user, active ownership pairing, EUDA temporal limits — see Compliance constraints), creates a PENDING record, sets up the billing hold (Workflow A) or validates the payment method (Workflow B), and emails the owner a secure approval link. The call returns a requestId and status — no data yet.

Step 3 — Monitor the request

Poll the list endpoints (filter by vin, requestStatus, consentStatus, with paging), or subscribe to a webhook to be pushed status changes:

Wait for requestStatus = APPROVED and consentStatus = GRANTED. See Data-request lifecycle & statuses.

Step 4 — Retrieve data

Historical — list deliveries, then fetch a time-limited download URL:

Real-time — once approved, read a telematics resource directly:

See the real-time telematics catalog for valid {resource} values.

Use this when an individual owner authorizes your app. PKCE means no client secret.

1. Your app: Generate PKCE verifier + challenge
2. Your app → Platform API: Redirect owner to /authorize (challenge)
3. Platform API → Nissan IdP: Redirect for login
4. Vehicle owner → Nissan IdP: Authenticate
5. Nissan IdP → Vehicle owner: Consent prompt
6. Vehicle owner → Nissan IdP: Approve
7. Platform API → Your app: Redirect to callback (auth code)
8. Your app → Platform API: POST /cms/oauth/token (code + verifier)
9. Platform API → Your app: access_token + id_token + refresh_token
10. Your app → Platform API: GET data (Authorization + X-Id-Token)
11. Platform API → Your app: Data

Step 1 — Generate a PKCE verifier and challenge (per authorization attempt)

// Keep the verifier private; send only the challenge to /authorize.
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const digest = await crypto.subtle.digest(
  "SHA-256",
  new TextEncoder().encode(verifier)
);
const codeChallenge = base64url(new Uint8Array(digest));

Step 2 — Redirect the owner to the authorize endpoint

{API_BASE}/cms/oauth/authorize
  ?account_id=YOUR_ACCOUNT_ID
  &client_id=YOUR_CLIENT_ID
  &redirectUri=https://your-app.example.com/callback
  &codeChallenge=BASE64URL_SHA256_OF_VERIFIER
  &codeChallengeMethod=S256

The owner logs in via the Nissan IdP, sees the plain-language consent prompt for the scopes you requested, approves, and is redirected back to your redirectUri with an auth code.

Step 3 — Exchange the code for tokens (on your callback, using the original verifier)

curl -X POST "{API_BASE}/cms/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE_FROM_CALLBACK",
    "redirect_uri": "https://your-app.example.com/callback",
    "client_id": "YOUR_CLIENT_ID",
    "code_verifier": "ORIGINAL_VERIFIER"
  }'

You receive an access_token, an id_token, and a refresh_token.

Step 4 — Call owner-scoped APIs with dual tokens

Every /cms/oauth/accounts/... call requires both headers:

Authorization: Bearer <access_token>
X-Id-Token: <id_token>

The owner-scoped endpoints mirror the M2M ones:

Step 5 — Refresh tokens before they expire

The refresh token rotates on each use — store the new one each time:

curl -X POST "{API_BASE}/cms/oauth/token/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "refreshToken": "YOUR_REFRESH_TOKEN"
  }'

A request moves through several states as the owner consents and data is delivered. Poll the list endpoints or use webhooks to track it. These are the authoritative enums returned by the API:

The consent lifecycle, in brief:

How to read the statuses together:

• PENDING / consentStatus = PENDING — created, owner notified, awaiting action. No data.
• APPROVED + GRANTED — the only state in which data is retrievable. Real-time reads and historical deliveries are available here.
• DECLINED / consentStatus = DENIED — owner rejected. Terminal; initiate a new request if still needed.
• EXPIRED (request) / consentStatus = EXPIRED — either the request lapsed before the owner acted, or the consent term ended. Terminal; create a fresh request.
• REVOKED — owner revoked an active grant; data stops immediately. Terminal for that grant.
• SUPERSEDED (consent) — a newer consent grant has replaced this one (e.g., re-scoped request).
• COMPLETED — a one-off request whose delivery has been fulfilled.
• INVALID / CANCELLED — failed validation (bad VIN, no ownership link, etc.) or was cancelled.

Historical (file delivery)

Historical results are prepared asynchronously and delivered as zipped CSVs via a time-limited pre-signed download URL (session/IP- restricted). The flow:

1. Request reaches APPROVED + GRANTED and (Workflow A) payment is captured.
2. List deliveries: GET .../historical/data-requests/{requestId}/data-deliveries.
3. Fetch the download URL: GET .../data-deliveries/{dataDeliveryId}/download.
4. Download promptly — the URL expires.

If you created the request via API and subscribed to webhooks, you'll receive a delivery-ready event instead of needing to poll.

Last-known value

Last-known packages return the most recent known value(s) synchronously as JSON — no date range, no async file. Availability is vehicle-dependent (see Data families); expect a single response per call.

Real-time (pull)

Once APPROVED + GRANTED, read the latest known state of a resource on demand:

GET {API_BASE}/cms/{m2m|oauth}/accounts/{account_id}/realtime/vehicles/{vin}/{resource}

Real-time (push)

Subscribe a webhook to receive events on state change instead of polling. Real-time push is event-driven (e.g., journey completed, charge-state changed, safety fault).

Real-time resources are read per vehicle via .../realtime/vehicles/{vin}/{resource}. Available {resource} values:

Subscribe a webhook to receive push notifications instead of polling — for consent status changes, historical delivery readiness, and real-time events.

1. Platform → Your endpoint: Challenge value
2. Your endpoint → Platform: Echo challenge
3. Platform: Save subscription (active)
4. Platform → Your endpoint: POST event + X-NiCoDap-Sig (HMAC-SHA256)
5. Your endpoint: Verify signature, then process

What you provide

• A publicly reachable HTTPS callback URL.
• An HMAC key (up to 32 characters) used to sign payloads so you can verify authenticity.

Manage subscriptions from the portal (or the webhook API, where available).

Registration handshake (ownership challenge)

When you register a callback URL, the platform verifies you own it before it will send events:

1. The platform sends a challenge to your URL.
2. Your endpoint must echo the challenge back in the response.
3. On a match, the subscription is saved and set active.

Runtime delivery & signature verification

At runtime, the platform POSTs each event to your URL with an HMAC-SHA256 signature computed over the body using your shared HMAC key, carried in the X-NiCoDap-Sig header.

Events to expect

• Consent lifecycle changes — e.g., consent granted, denied, revoked, expired (carrying the requestId).
• Historical delivery ready — file download is available.
• Real-time telemetry push — e.g., the telemetry-push event and event-driven topics such as journey completed, charge-state changed, and safety fault, depending on the subscribed package.

These are EUDA/GDPR constraints enforced by the platform. Designing for them up front avoids confusing rejections and partial results.

Temporal limits on historical requests

• Earliest requestable date: 12 September 2025 (EUDA effective date). You cannot request data older than this.
• Maximum 90 days per historical request. Split longer ranges into multiple requests.
• Lookback limited to ~3 years. Older history is not available.

Ownership / entitlement (Gate 3)

• Data is only eligible for the portion of your requested window during which the consenting owner actually owned the vehicle. A valid request can therefore return a shorter window than asked.
• Entitlement resolution differs by vehicle generation: for older generations an active ownership link suffices; newer generations additionally verify the active driver against the linked owner. The net effect for you: don't assume every request yields the full range — handle partial results.

Data minimization (Gate 2)

• You receive exactly the packages/scopes the owner approved. Need more? Initiate a new request.

Governance (Gate 1)

• Sanctioned or gatekeeper-designated entities are blocked at login and at request time.

Retention & deletion

• Delivered files and decisions are retained as audit records under the platform's retention policy. Financial records persist for tax compliance even after account deletion.

• The API Gateway applies rate-limiting policies. Build in retry-with-backoff and treat 429 as transient.
• Validate against a development account (sandboxed, vehicle-count-limited) before going to production.
• Real-time/webhook delivery suits self-serve SME-to-mid volumes. If sustained run-rate or frequency grows beyond the platform's managed-streaming threshold, that's a managed high-throughput streaming tier conversation — contact your account team rather than working around webhook limits.
• Token hygiene: store the rotating refresh token after every refresh (App); never ship the client secret to a client device (M2M).

The reference below is generated from the live OpenAPI specification. Use it for exact request/response schemas and to try endpoints interactively.

In the portal, the interactive Swagger UI is embedded below. The OpenAPI document is served (per environment) from:

{API_BASE}/cms/openapi-by-tag.json?tags=b2b-developer-data-requests,realtime-data