# Authorization

## Getting access

Access to the VirtualCar360 API requires an active API key.

The API key is generated individually for each customer and can be assigned to a single account, a single location or multiple accounts within a dealer group.

To obtain access:

1. Contact VirtualCar360 support.
2. Provide information about the planned integration.
3. Receive the access credentials.
4. Run integration tests.


## Security

- Never publish an API key in browser-side code for direct API calls.
- Store keys in secure secret storage.
- Rotate keys if a security incident occurs.
- Do not log full URLs containing the `key` parameter.


# API Authorization

VirtualCar360 API uses API key authentication. The key is passed as the `key` query parameter and identifies the account, location or account group that the integration can access.

All API endpoints require a valid API key. Without a valid key, the integration should not expect to retrieve galleries, photos, hotspots or video links.

Important
In the current API version, the key is passed as the `key` query string parameter, not as an `Authorization` header.

## Base URL

All API endpoints are available under the following base URL:

```txt
https://img-out.virtualcar360.pl/api/v6.0/virtual-360
```

Example request:

```txt
https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/WBA1234567890?key=YOUR_API_KEY
```

## The `key` parameter

The `key` parameter is required in every API request.

| Parameter | Required | Description |
|  --- | --- | --- |
| `key` | yes | API key assigned to an account, location or account group in VirtualCar360. |


## Key types

### Single-location key

A standard key is assigned to one dealership location or account. It is suitable for a single showroom, brand or website.

### Group key

For larger organizations, VirtualCar360 can prepare a group key that aggregates data from multiple accounts or locations. This model is useful for multi-brand dealers, dealer groups and central CRM or DMS integrations.

Tip
If one integration should access multiple locations, contact VirtualCar360 support to configure a group key.

## Recommended backend proxy model

For direct API integrations, the safest model is to call VirtualCar360 from your backend, not directly from the browser.

Recommended flow:

1. The frontend calls the customer's backend.
2. The backend injects the `key` parameter.
3. The backend calls the VirtualCar360 API.
4. The backend returns only the required data to the frontend.


```txt
Customer frontend
  -> GET /api/vehicles/{vin}/gallery

Customer backend
  -> GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/{vin}?key=YOUR_API_KEY

Customer backend
  -> response to frontend without exposing the API key
```

## Error handling

If a request does not return the expected data, check:

- whether the `key` parameter was provided,
- whether the key is valid,
- whether the key has access to the correct location,
- whether the correct key type is used,
- whether VIN, registration number or `carId` are valid,
- whether the vehicle has a gallery in VirtualCar360.


Typical API responses:

| Code | Meaning |
|  --- | --- |
| `200` | Request completed successfully. |
| `400` | Invalid request parameters. |
| `404` | No gallery found for the provided criteria. |
| `500` | Server error. Contact VirtualCar360 support. |


Note
If the key is valid but the API returns no data for a vehicle, the most common reason is that no gallery exists for the given VIN or registration number, or the key does not have access to the correct location.