# One key for the Tuning and UDS APIs

Create a key at [Account → Settings → API access](https://redlineautohaus.com/account/settings/api). Sign in with an active, verified RedlineAutohaus account and confirm your password. The complete key is shown once; copy it into your integration's secret storage. Stored records contain a hash, never a recoverable secret.

Send `Authorization: Bearer <REDLINE_API_KEY>` over HTTPS. Do not send cookies with a key or put keys in URLs. Keys do not authorize AutoClever, Firebase, WinOLS MCP or Ghidra MCP operations.

## Included access and optional permissions

Every active key includes `uds:read` and `uds:write`. This permits evidence submission and reading its status without an approval step, opt-in permission or manually provisioned workspace. The server automatically creates a private account workspace on first UDS use. All keys belonging to that account share that workspace. Other accounts' evidence is private.

| Additional permission | Available operations |
| --- | --- |
| `tuning:read` | Own contributions, upload configuration, credit balance/history, grants, acquisitions, download history and download quotes |
| `tuning:upload` | Create contributions, upload files, edit metadata/dependencies, submit, retry and cancel your contributions |
| `tuning:download` | Download versions the account is already entitled to access |
| `tuning:spend` | Acquire an exact file version using an existing credit quote and the account's balance |
| `uds:sensitive-read` | Read sensitive identifiers, raw payloads and evidence within the authorized workspace |
| `uds:artifact-read` | Read original UDS artifacts; also requires `uds:sensitive-read` |

Public Tuning catalogue metadata does not require a key. An invalid credential is rejected even on a public route. Staff roles do not grant integration keys staff-only visibility or free downloads. Existing entitlements and deliberate file grants still apply. Key management, profile/password changes, user administration and verifier worker operations are not available to customer API keys.

## First requests

Set `REDLINE_API_KEY` in your environment without committing it to source control. These examples only read data:

```sh
curl --fail-with-body https://api.redlineautohaus.com/api/v1/uds/capabilities \
  -H "Authorization: Bearer $REDLINE_API_KEY"
curl --fail-with-body https://api.redlineautohaus.com/api/v1/tuning/me/credits \
  -H "Authorization: Bearer $REDLINE_API_KEY"
```

JavaScript (server-side; do not expose your key in browser bundles):

```javascript
const headers = { Authorization: `Bearer ${process.env.REDLINE_API_KEY}` };
for (const path of ['uds/capabilities', 'tuning/me/credits']) {
  const response = await fetch(`https://api.redlineautohaus.com/api/v1/${path}`, { headers });
  if (!response.ok) throw new Error(`API returned ${response.status}`);
  console.log(await response.json());
}
```

Python (standard library):

```python
import json, os, urllib.request
for path in ("uds/capabilities", "tuning/me/credits"):
    request = urllib.request.Request(
        "https://api.redlineautohaus.com/api/v1/" + path,
        headers={"Authorization": "Bearer " + os.environ["REDLINE_API_KEY"]})
    with urllib.request.urlopen(request, timeout=30) as response:
        print(json.load(response))
```

## Submit and inspect

UDS: use the [quickstart](../uds/quickstart.md) to create a source, session, source record and exact messages. Use the same Bearer key as `UDS_TOKEN` in the existing examples. No vehicle identity is required to start. Claims and candidate definitions stay unreviewed until an authorized reviewer acts. Protected identifiers and raw bytes may be redacted unless the key has the optional sensitive-read permission.

Tuning: create `POST /contributions`, then use the returned `contributionId` with `POST /contributions/{id}/items`. Send multipart fields `file` and JSON `metadata`, including the current contribution rights version obtained from `GET /contribution-config`. For a full upload integration, select both `tuning:read` and `tuning:upload`. Use the [Tuning OpenAPI contract](../tuning/openapi.json) for exact shapes and dependency rules. Submit with `POST /contributions/{id}/submit` and the current `If-Match` value. Poll `GET /contributions/{id}` or stream `GET /contributions/{id}/events` using Authorization and, on reconnect, `Last-Event-ID`. The website's Socket.IO connection continues to use its browser session.

A download GET never purchases access. First request a quote using `POST /files/{id}/download-quote` (`tuning:read`), explicitly confirm its price in your application, and call `POST /download-acquisitions` with `quoteId` (`tuning:spend`). Then use the exact-version download URL (`tuning:download`). Credit acquisition retries with the same Idempotency-Key do not charge again.

All UDS POSTs and Tuning contribution/accounting mutations require a stable `Idempotency-Key`. Keep it unchanged when retrying the same operation and body. Tuning idempotency is separated by integration key and browser session access class; UDS also binds it to scope, credential and route. New keys use a new retry namespace. Honor `If-Match` where documented. Bearer requests do not require Origin or CSRF headers; browser cookie mutations still require both.

## Approved protocols and administrator controls

All keys can read deliberately published knowledge at `GET /api/v1/uds/knowledge/protocols` and `GET /api/v1/uds/knowledge/protocols/{id}`. This is a separate curated view, not a read of other users' private definitions or evidence. It contains explicitly composed protocol metadata, applicability and command steps; no private source record is automatically copied. Withdrawal, changed review state, superseding/merging, or scope removal hides the affected publication. This API does not execute commands on vehicles.

A platform administrator uses [Administration → API access](https://redlineautohaus.com/admin/api-access) to control four capabilities: approval, revision/merge, redaction and publication. They default off. Turning them off leaves evidence ingestion available. An eligible admin-owned developer key needs both a corresponding key permission (`uds:approve`, `uds:revise`, `uds:redact` or `uds:publish`) and an explicit grant for the target UDS workspace. To address another granted workspace, send its UUID in `X-UDS-Scope`. Ordinary customers cannot select another workspace or self-grant these permissions.

The global switches and explicit workspace grants also cover legacy `uds_` service credentials and Firebase shop identities. Their original authentication, scope and permissions still apply; old `uds:review` alone is insufficient. An administrator enables the required capability and grants access to the specific credential. Publication requires a current verified, constrained definition version and an explicitly composed public document. See the [UDS OpenAPI](../uds/openapi.json) publication operations for the request schema.

## Rotation, revocation, limits and errors

Keys expire after 1–365 days (the account UI offers 30, 90 or 365). Up to ten nonexpired, nonrevoked keys may exist per account, including disabled keys. Rotation revokes the old key immediately or allows a ten-minute overlap, and displays the replacement secret once. At the ten-key limit, immediate rotation works; overlap requires a free slot. Rotation preserves allowed permissions and administrative workspace grants. Revoked keys cannot be reactivated. An administrator's disable cannot be undone by the owner.

Password changes and resets revoke all keys. Suspended, unverified or API-disabled accounts cannot use keys. Demotion immediately removes administrative capabilities. Revocation and policy updates wait for already-authorized database mutations to finish; once the change returns, subsequent commits and cached privileged replays are denied. Accepted background evidence ingestion continues processing previously submitted work. Bytes already downloaded cannot be recalled.

The default account quota is 1,200 requests/minute shared across its keys, with a maximum of 600/minute per key. Administrators can lower account limits. UDS scope quotas and upload/credit-specific limits also apply. Status polling counts toward the quota; use reasonable intervals and backoff.

| Status | Typical meaning | Response |
| --- | --- | --- |
| 400 | Mixed cookies/key, missing Idempotency-Key or invalid request | Correct the request |
| 401 | Invalid, expired, disabled or revoked credential | Rotate or replace through account settings |
| 403 | Missing permission, unavailable privileged capability, or ungranted scope | Check key settings; evidence submission does not need a special grant |
| 404 | Missing record or another account's private record | Check ownership and IDs |
| 409 / 412 | Changed state, quote or ETag | Read current state and retry deliberately |
| 429 | Account, key or product quota | Back off; honor Retry-After if present |
| 503 | Module or key access unavailable | Retry with backoff; retain original idempotency key |

The API never returns a saved secret from key lists, administrative screens, audit events or documentation. Manage and recover access through the authenticated account website.