BMW private UCP source
Catalog and authentication
The private client is ai_bmw.sources.ucp_private. The public client is
ai_public_api.bmw.ucp and uses https://prod.ucp.bmw.cloud.
Private assets use the ucp_private source name, for example
bmw/us/raw/ucp_private_models.
UcpPrivateRawComponent accepts these regional settings. The repository
configures private UCP for the US market.
| Setting | US configuration |
|---|---|
api_base_url | https://author.m2m.ucp.bmw.cloud |
data_source | sprint-pre-soc |
country | us |
language | en |
currency | USD |
model_year_window | 1 |
token_url | PROD OAuth endpoint listed below |
The shared client preserves model codes verbatim. Without model_year_window,
the component selects all models. The window applies only to country us,
where the first two model-code characters encode the model year.
Credentials are read at fetch time. Each region specifies its credential environment-variable names:
| Setting | US environment variable | Value |
|---|---|---|
api_key_env | BMW_US_UCP_API_KEY | Pre-SOC API key |
client_id_env | BMW_US_UCP_CLIENT_ID | BMW UCP OAuth client ID |
client_secret_env | BMW_US_UCP_CLIENT_SECRET | BMW UCP OAuth client secret |
The OAuth client secret and API key are separate credentials. Inject them into local processes or the BMW branch deployment's run containers using the secret manager. Keep credential values out of configuration files and source control.
The default token endpoint is
https://emea.prod.alpha.sso.bmwgroup.com/auth/oauth2/realms/root/realms/alpha/access_token.
The client posts form data with grant_type=client_credentials and scope
machine2machine client_<client_id>. Author and Prod use PROD OAuth credentials.
Release uses https://release.m2m.ucp-int.bmw.cloud and the corresponding token
endpoint under https://emea.int.alpha.sso.bmwgroup.com with INT credentials.
Every UCP request sends both Authorization: Bearer <token> and x-api-key.
A fetch shares one token across its workers and renews it before expiry. Token
transport failures and HTTP 429 or any 5xx receive up to three retries;
invalid credentials and malformed token responses fail the fetch. Tokens are
not persisted. Credentials are excluded from recorded request data and logs.
API and token requests use HTTPS without redirects.
Original endpoints
UCP calls a localized description a phrase: the display text for a model, option
or body style in one language, with the interval over which that wording applies.
The phrases in a resource name and in a response body are that vendor term, not
a description of the code.
The endpoint paths use these substitutions:
| Placeholder | Value |
|---|---|
{source} | Configured catalog source; sprint-pre-soc for the US |
{model} | Original model code from the models response |
{country} | Configured country; us for the US |
{language} | Configured language; en for the US |
{currency} | Configured currency; USD for the US |
| Raw resource | GET path |
|---|---|
models | /vehicles/sources/{source}/brands/bmwCar/countries/{country}/models |
primary_data | /vehicles/sources/{source}/brands/bmwCar/countries/{country}/models/{model}/primary-data |
options | /vehicles/sources/{source}/brands/bmwCar/countries/{country}/models/{model}/options |
model_phrases | /localisations/original-phrases/sources/{source}/brands/bmwCar/countries/{country}/models/languages/{language} |
option_phrases | /localisations/original-phrases/sources/{source}/brands/bmwCar/countries/{country}/models/{model}/options/languages/{language} |
prices | /pricing/internal/original-prices/price-lists/{source}/brands/bmwCar/countries/{country}/models/{model}?currency={currency} |
Model phrases are fetched once per configured country and language.
The request has no model or effect-date filter. Each model has a phrases array containing the original descriptions
and validFrom/validTo intervals. The raw response preserves every interval,
including missing bounds and placeholder descriptions such as SALES_DESCR.
A model absent from this response has no model-name entry in that capture.
The enumerator has no model filter and its complete response is retained.
US per-model requests use an inclusive model-year window around the partition
year: with model_year_window: 1, a 2026 partition includes model years
2025–2027. The year is 2000 plus the first two model-code characters. A wider
window includes model years the BYO catalog has no configurator for, and rules
for those years reference features the catalog cannot resolve.
Invalid year prefixes fail enumeration. The model coverage check reports
eligible and skipped counts and every skipped model code.
Each eligible model produces four original endpoint requests.
Missing configuration bounds leave the corresponding request dates null.
The client still requests all four per-model resources.
Four concurrent workers use the shared ai_http retry handling, with three
retries per request. Raw rows preserve the complete response body and the
standard raw schema. _request_params records:
- Request URL and resource.
- Catalog source and country scope.
- Country, language, and currency.
- Capture date and applicable model codes.
- Selected effect and order dates, when applicable.
The model coverage check requires exactly one data or expected-unavailable response per eligible request. It reports response counts by availability. For unavailable prices, it reports:
- Model code.
- HTTP status and UCP error code.
- Reason for unavailability.
The blocking fetch_attempts check has a zero terminal-failure tolerance.
Empty or inconsistent model enumeration and malformed response bodies fail
validation.
Only these US original-prices responses are accepted as expected unavailability:
| HTTP status | UCP errorCode | UCP errorMessage | Recorded reason |
|---|---|---|---|
| 404 | PRI_B_1015 | any | no_model_price |
| 400 | PRI_B_1004 | starts with "Model not found" | model_not_in_price_catalog |
UCP also returns PRI_B_1004 for errors unrelated to a missing model; see
Error responses.
These outcomes preserve the original error body. Their _request_params include:
availability: "unavailable".http_status.ucp_error_code.unavailable_reason.
Successful data responses record availability: "available".
An accepted unavailable response has a successful fetch outcome while retaining
its actual HTTP status. It contains no price data. Other error responses use normal failure and retry
handling. Authentication failures and exhausted retries fail the fetch.
Captured evidence
Replay fixtures live under projects/ai_bmw/tests/data/ucp/.
1029-price-unavailable.json and 277P-price-unavailable.json capture the
Author / sprint-pre-soc missing-price responses listed above.
model-phrases-pre-soc.json is a complete Author / sprint-pre-soc response
containing 1,175 model entries. Model 277P has two phrase intervals.
The other UCP response fixtures are Author / sprint-sim captures. Credentials
are supplied outside the payload.
models.json contains 1,201 unfiltered models; models-filtered.json is a
comparison response for 1029 and 277P. Model 277P contains:
- 455 rules.
- 248 options.
- 11 packages.
- 150 combination-price entries.
The historical 1029 primary response has 224 rule statements, including two intervals of 15803.
byo-typelist.json contains 136 model identity mappings.
overridden-models.json and 277P-overridden-options.json are comparison
fixtures. They contain no rule collection; the ingestion uses primary-data
for rules and original endpoints for product data with validity intervals.
A local curl configuration can supply both authentication headers for pre-SOC requests. Keep it outside the repository and refresh the bearer token using the client-credentials endpoint before it expires.