Skip to main content

Authentication

All API requests require authentication via Bearer token. This guide covers how to authenticate with the HMP API.

Overview​

HMP uses JWT (JSON Web Tokens) for API authentication. Tokens are obtained by authenticating with valid credentials and must be included in all subsequent API requests.

Getting Started​

Obtain API Credentials​

  1. Log in to the HMP Dashboard
  2. Navigate to Settings > API Keys
  3. Create a new API key
  4. Note your Client ID and Client Secret

Authentication Flow​

Obtain Access Token​

Request​

curl -X POST https://api.hmpcloud.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

Response​

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

Using Access Tokens​

Include the access token in the Authorization header of all API requests:

curl -X GET https://api.hmpcloud.com/v1/reservations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Property-ID: prop_abc123"

Required Headers​

HeaderDescription
AuthorizationBearer token from authentication
X-Property-IDProperty identifier for the request
Content-Typeapplication/json for POST/PUT requests

Refresh Tokens​

Access tokens expire after 24 hours. Use the refresh token to obtain a new access token:

curl -X POST https://api.hmpcloud.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
  }'

User Authentication​

For user-based authentication (e.g., mobile apps):

curl -X POST https://api.hmpcloud.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@hotel.com",
    "password": "your_password"
  }'

Response​

{
  "user": {
    "id": "user_123",
    "email": "user@hotel.com",
    "name": "John Doe",
    "roles": ["front_desk"]
  },
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

Token Structure​

The JWT access token contains:

{
  "sub": "user_123",
  "email": "user@hotel.com",
  "roles": ["front_desk", "cashier"],
  "properties": ["prop_abc123", "prop_def456"],
  "iat": 1708000000,
  "exp": 1708086400
}

OAuth 2.0 (SSO)​

HMP supports OAuth 2.0 for single sign-on with supported providers.

Initiate OAuth Flow​

GET https://api.hmpcloud.com/v1/auth/oauth/google
  ?redirect_uri=https://yourapp.com/callback
  &state=random_state_string

Handle Callback​

Your callback URL receives an authorization code:

https://yourapp.com/callback?code=AUTH_CODE&state=random_state_string

Exchange the code for tokens:

curl -X POST https://api.hmpcloud.com/v1/auth/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE",
    "redirect_uri": "https://yourapp.com/callback"
  }'

Error Responses​

Invalid Credentials​

{
  "error": "invalid_credentials",
  "message": "The provided credentials are invalid"
}

Status: 401 Unauthorized

Token Expired​

{
  "error": "token_expired",
  "message": "The access token has expired"
}

Status: 401 Unauthorized

Insufficient Permissions​

{
  "error": "forbidden",
  "message": "You do not have permission to access this resource"
}

Status: 403 Forbidden

Best Practices​

  1. Store tokens securely - Never expose tokens in client-side code
  2. Use HTTPS - All API calls must use HTTPS
  3. Implement refresh logic - Handle token expiry gracefully
  4. Rotate credentials - Regularly rotate API keys
  5. Use appropriate scopes - Request only necessary permissions

Rate Limiting​

API requests are rate limited:

  • Standard: 100 requests per minute
  • Authentication: 10 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1708000060