# Space Hospitality API

The Space Hospitality API provides integration capabilities for hospitality management systems to work with the [Salto Space access control platform](https://support.saltosystems.com/space/) as a credential provider for Apple Wallet.

## Features

- **Digital room keys**: Create and manage {{< glossary_term "apple_wallet_key" >}}Apple Wallet keys{{< /glossary_term >}} for hotel rooms
- **Key lifecycle management**: List, retrieve, and delete individual room keys
- **Provision token generation**: Generate tokens for wallet key provisioning
- **Guest management**: Handle check-in and check-out operations with automatic key invalidation
- **Security**: Bearer token authentication for secure access
- **Immediate operations**: Instant key activation, deactivation, and room status changes

## Solution architecture

![Space Hospitality API architecture](images/space-hospitality-architecture.svg "Space Hospitality API architecture")
{.zoomable-image}

The Hospitality API integration requires coordination between three key components:

1. **Credential Manager Service**: Your hospitality management system that initiates wallet key requests
2. **Salto Space**: The access control platform that manages credentials and hardware
3. **Salto WalletHub**: Salto's cloud service that handles Apple Wallet key provisioning

## Prerequisites {#prerequisites}

Before you begin integration, ensure the following requirements are met:

### Space installation requirements {#space-requirements}

The property's Space installation must have:

- **Space version**: 6.10 or later (6.12+ recommended for full feature support)
- **Required licenses**:
  - `SPACE-OPT-0041`: Wallet Guest Keys
  - `SPACE-OPT-0030`: Web Services Defined by User (required for development/testing environments)
- **Hardware**: Compatible NFC-enabled Salto devices with required firmware versions
- **NCoder dongle**: At least one Ethernet NCoder (firmware 0172, version 01.15 or higher) working in dongle mode

See the [Space user guide](https://support.saltosystems.com/space/user-guide/operator/general-options/wallet-keys) for more details.

### Network configuration {#network-requirements}

The property's network must allow:

- **Inbound connections**: From your credential manager service to the Space Hospitality API endpoint
- **Firewall rules**: Configured to accept requests from your service's IP addresses
- **TLS certificate**: Valid certificate for the Space Hospitality API endpoint

See [Connectivity considerations](https://support.saltosystems.com/space/user-guide/systems-admin/hospitality-api/) for detailed network configuration.

### Configuration values {#configuration-values}

You will need to provide or obtain the following values:

**To provide to Salto/property:**

- Your credential manager service's IP address and port (for firewall rules)
- Your TCI (Tag Class Identifier): A unique 3-byte (6 hexadecimal character) identifier for wallet pass identification

**To obtain from Salto/property:**

- Space Hospitality API endpoint URL (public IP or domain) and port
- API authentication key (generated in Space)
- WalletHub credentials (provided by Salto for production; separate credentials for development)

**Fixed values (provided here for reference):**

- Salto's Apple-assigned credential provider ID: `ORG-d8107156-8533-42b6-8702-694451e6c0ad`

## Getting started

### Environment setup {#environment-setup}

Two environments are available for integration:

**Development environment:**

- WalletHub URI: `https://dev.wallethub.saltoapis.com`
- WalletHub Account URI: `https://dev.account.saltosystems.com`
- Use for initial development and testing
- Requires `SPACE-OPT-0030` license to configure custom URIs

**Production environment:**

- WalletHub URI: `https://wallethub.saltoapis.com`
- WalletHub Account URI: `https://account.saltosystems.com`
- Use for live deployments
- Default configuration in Space

### Space configuration {#space-configuration}

The property's Space installation must be configured as follows:

1. **Hospitality API setup**:
   - Select **Hospitality API (Salto)** integration type in **System** > **General options** > **Wallet keys**
   - Generate API authentication key
   - Configure API port in ProAccess Space Configurator
   - Set up TLS certificate

2. **WalletHub configuration**:
   - Enter WalletHub credentials (provided by Salto)
   - Test connection
   - Activate the integration

3. **SAM & Issuing configuration**:
   - Enable **Wallet** in active keys
   - Select **Salto** as credential provider
   - Enter your TCI value
   - Generate key using NCoder dongle

See the [wallet keys configuration guide](https://support.saltosystems.com/space/user-guide/operator/general-options/wallet-keys) for detailed steps.

### Authentication {#authentication}

The API uses Bearer token authentication.
The API key is generated in Space during the Hospitality API setup and must be included in all API requests:

```http
Authorization: Bearer YOUR_API_KEY
```

[Contact Salto](https://saltosystems.com/en/contact/) to coordinate the integration setup and obtain necessary credentials.

### Integration workflow {#integration-workflow}

A typical integration workflow follows these steps:

1. **Property setup**: Space installation is configured with all prerequisites met
2. **Network configuration**: Firewall rules allow communication between systems
3. **Credentials exchange**: API keys and TCI values are shared
4. **Testing**: Validate operations in development environment
5. **Production deployment**: Switch to production WalletHub environment
6. **Operations**: Implement check-in/check-out workflows

## Apple Wallet provisioning flow {#provisioning-flow}

During Apple Wallet provisioning, your credential manager sends an `authorizationBlob` to Apple.
Apple forwards this blob to WalletHub (Salto's credential provider) when calling `getCadData`.
This section describes the required values and expected format.

### Credential provider ID {#credential-provider-id}

Salto's Apple-assigned credential provider ID is:

```txt
ORG-d8107156-8533-42b6-8702-694451e6c0ad
```

Use this value as the `credentialProviderId` when building your Apple Wallet provisioning request.

### Authorization blob metadata {#authorization-blob}

The `authorizationBlob` metadata object must include the `provision_token` key:

```json
{
  "provision_token": "<base64-encoded provision token>"
}
```

The provision token is obtained from the `GenerateProvisionToken` endpoint and **must be Base64-encoded** before being placed in the blob.
WalletHub Base64-decodes and then decrypts the token on receipt.

### End-to-end provisioning steps {#provisioning-steps}

1. Call `POST /v1/rooms/{room}/keys` to create a room key
2. Call `POST /v1/rooms/{room}/keys/{key}:generateProvisionToken` to obtain a provision token
3. Base64-encode the returned `provision_token` value
4. Build the `authorizationBlob` metadata with the encoded token under the `provision_token` key
5. Set `credentialProviderId` to `ORG-d8107156-8533-42b6-8702-694451e6c0ad`
6. Pass these values to Apple during wallet provisioning - Apple forwards the blob to WalletHub automatically

## Key operations

### Room check-in

Creates a room access period and invalidates any previous keys for the same room.
This ensures only the current guest can access the room.

### Key creation

Generate new Apple Wallet keys for specific rooms with defined time periods.
Keys are provisioned through Apple Wallet and use NFC to unlock compatible Salto devices.

### Key management

List all keys for a room, retrieve individual key details, or delete specific keys as needed.
Useful for troubleshooting and managing guest access.

### Provision tokens

Generate time-limited tokens that allow wallet credential retrieval.
These tokens are used by the Apple Wallet provisioning flow.
Once obtained, the token must be Base64-encoded and passed in the `authorizationBlob` as the `provision_token` field.
See [Apple Wallet provisioning flow](#provisioning-flow) for the full details.

### Room check-out

Remove all keys and invalidate room access when a guest checks out.
Ensures immediate revocation of access privileges.

{{% info-panel %}}
**Note**: This API only supports Apple Wallet keys for hotel guest rooms.
Physical cards and staff keys are not supported through this API.
{{% /info-panel %}}

## Important considerations {#considerations}

- **Character restrictions**: The following characters are not allowed in room names and key identifiers: `?`, `/`, `:`, `%`, `#`, `\`
- **Immediate operations**: All key operations take effect right away on compatible online devices
- **Key lifecycle**: Keys are automatically invalidated during check-in or check-out operations
- **Network dependency**: The Space server must be accessible via the configured Hospitality API endpoint
- **TCI uniqueness**: Each credential manager integration requires a unique TCI value

## Testing hardware {#testing-hardware}

For integration testing purposes, compatible test hardware includes:

- NFC-enabled Salto locks with updated firmware
- NCoder dongle (firmware 0172, version 01.15+)
- Apple devices with Wallet app (iPhone 6S or later, Apple Watch Series 1 or later)

Contact your Salto representative for a complete list of compatible hardware for testing.

## Support and troubleshooting {#support}

For integration support:

1. **Review documentation**: Check the [Space user guide](https://support.saltosystems.com/space/) for configuration details
2. **Verify prerequisites**: Ensure all licenses, hardware and network requirements are met
3. **Check connectivity**: Verify firewall rules and endpoint accessibility
4. **Test credentials**: Confirm API keys and WalletHub credentials are correct
5. **Contact Salto**: Reach out to your Salto partner or [contact Salto support](https://saltosystems.com/en/contact/)

When reporting issues, provide:

- Space version and license information
- API request/response details (without sensitive credentials)
- Network configuration details
- Error messages or unexpected behavior descriptions

## Download OpenAPI specification

- {{< downloadable "<https://developer.saltosystems.com/space/hospitality-openapi.yaml>" "HospitalityService API (YAML): " "version: 0.0.1" >}}

## Additional resources

- [Wallet keys configuration guide](https://support.saltosystems.com/space/user-guide/operator/general-options/wallet-keys)
- [SAM & Issuing options for wallet keys](https://support.saltosystems.com/space/user-guide/operator/sam-and-issuing-options/wallet)
- [Connectivity considerations](https://support.saltosystems.com/space/user-guide/systems-admin/hospitality-api/)
- [Space system requirements](https://support.saltosystems.com/space/user-guide/systems-admin/system-requirements)