Authentication

How Hotelinking authenticates with your API. Configure credentials during onboarding to match your system's requirements.

Overview

Hotelinking supports 9 authentication configurations when calling partner APIs. The method is auto-detected from your credential structure, or can be set explicitly via the auth_method field.

Credentials are configured once during integration setup. Hotelinking handles token refresh, signature generation, and header injection automatically on every API call.

Authentication Methods

API Key (Header)

Sends your API key in a custom HTTP header. Supports an optional prefix (e.g. "Bearer ").

auth_method: "api_key_header"

{
  "api_key": "your-key",
  "header_name": "X-API-Key",
  "prefix": ""
}

Result: X-API-Key: your-key. If prefix is set (e.g. "Bearer "), the value becomes X-API-Key: Bearer your-key.

API Key (Query Parameter)

Sends your API key as a URL query parameter appended to every request.

auth_method: "api_key_query"

{
  "api_key": "your-key",
  "query_param_name": "api_key"
}

Result: ?api_key=your-key appended to the request URL.

Bearer Token

Sends a static bearer token in the Authorization header.

auth_method: "bearer_token"

{
  "oauth_tokens": {
    "access_token": "your-token"
  }
}

Result: Authorization: Bearer your-token

Basic Auth

Sends a Base64-encoded username and password in the Authorization header.

auth_method: "basic_auth"

{
  "username": "user",
  "password": "pass"
}

Result: Authorization: Basic dXNlcjpwYXNz where the value is base64(username:password).

OAuth 2.0 Client Credentials

Fetches an access token from your token endpoint using the client credentials grant. Tokens are cached and auto-refreshed with a 5-minute expiry buffer.

auth_method: "oauth2_client_credentials"

{
  "grant_type": "client_credentials",
  "token_url": "https://auth.example.com/token",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

Tokens are automatically refreshed when they expire. Hotelinking checks token validity before each request and re-authenticates with a 5-minute buffer before expiry.

OAuth 2.0 Password

Fetches an access token using the resource owner password credentials grant. Requires a token endpoint, client credentials, and user credentials.

auth_method: "oauth2_password"

{
  "grant_type": "password",
  "token_url": "https://auth.example.com/token",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "username": "user",
  "password": "pass"
}

HMAC-SHA512

Generates a signature from your API key, shared secret, and the current timestamp. The signature is recomputed on every request.

auth_method: "hmac_sha512"

{
  "api_key": "your-key",
  "shared_secret": "your-secret"
}

Result:

Authorization: HMAC APIKey=<key>,Signature=sha512(<key>+<secret>+<ts>),timestamp=<ts>

An optional auth_header_prefix field can customize the header format.

Custom Token Endpoint

Calls your authentication endpoint to fetch a token, then uses that token in subsequent API requests. Supports token caching with configurable expiry.

auth_method: "custom"

{
  "auth": {
    "url": "https://api.example.com/login",
    "credentials": {
      "username": "user",
      "password": "pass"
    },
    "tokenFieldName": "token",
    "tokenHeaderName": "Authorization",
    "tokenPrefix": "Bearer "
  }
}

Hotelinking POSTs the credentials to your url, extracts the token from the field specified by tokenFieldName, and sends it in subsequent requests via the header defined by tokenHeaderName with the given tokenPrefix.

None (Body-Based Auth)

No HTTP-level authentication is applied. Use this when your API authenticates via parameters included directly in the request body (e.g. API tokens sent as JSON fields).

auth_method: "none"

{
  "auth_method": "none"
}

With this method, no Authorization header is added. Ensure your API credentials are included in the request body via the endpoint's body template configuration.

Auto-Detection

If auth_method is not explicitly set in your configuration, Hotelinking automatically detects the authentication method from the shape of your credentials.

Config shape	Detected method
`api_key` + `shared_secret`	hmac_sha512
`api_key` + `header_name`	api_key_header
`api_key` + `query_param_name`	api_key_query
`grant_type: "client_credentials"`	oauth2_client_credentials
`grant_type: "password"`	oauth2_password
`username` + `password` (no token URL)	basic_auth
`oauth_tokens` or `access_token`	bearer_token
`url` + `credentials`	custom

Detection order matters. For example, a config with both api_key and shared_secret will be detected as hmac_sha512, not api_key_header. Set auth_method explicitly to override auto-detection.

Security Best Practices

Secure storage

Keep credentials in environment variables or a secrets manager. Never commit API keys or secrets to source control.

Rotate keys regularly

Rotate API keys and secrets on a regular schedule. Revoke compromised credentials immediately and notify us to update the configuration.

HTTPS only

All API endpoints must use HTTPS. Hotelinking will not send credentials over unencrypted HTTP connections.

Token expiry

Set appropriate expiry times for OAuth tokens. Hotelinking auto-refreshes tokens with a 5-minute buffer before expiry.

Credential Hierarchy

Credentials are configured at the tenant level and shared across all brands within that tenant using a given integration. These shared credentials apply to all properties using that integration.

When a specific brand requires different credentials (e.g. a per-property access token), overrides can be configured at the brand level via the external_brand_id or custom configuration overrides.

configuration hierarchy

Tenant Integration Config   (shared credentials)
  └── Brand Integration       (per-property overrides)
       ├── external_brand_id  (brand's ID in external system)
       └── config_overrides   (credential or setting overrides)

At execution time, Hotelinking merges configuration from the integration definition, tenant config, and brand overrides into a single credential set. Brand-level values take precedence over tenant-level values.