Jasmine Smart Homes API Guide

Welcome! This interactive guide provides everything you need to integrate with the Jasmine Smart Homes platform. You'll learn how to use our OAuth 2.0 flow to authorize users and how to handle smart home intents for device control. This application is designed to make exploring our API intuitive and efficient.

Authentication & Authorization

We use the industry-standard **OAuth 2.0 Authorization Code Grant** to ensure users can securely link their accounts to your application. The process involves three main steps, which you can see visualized in the interactive panel to your right (on desktop).

GET https://api.jasminesmarthomes.com/webhook/auth
  ?response_type=code
  &client_id={CLIENT_ID}
  &redirect_uri={REDIRECT_URI}
  &scope=smart_home
  &state={CSRF_TOKEN}

POST https://api.jasminesmarthomes.com/webhook/token
Content-Type: application/x-www-form-urlencoded

client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}
&code={AUTH_CODE}
&grant_type=authorization_code
&redirect_uri={REDIRECT_URI}

POST https://api.jasminesmarthomes.com/webhook/token
Content-Type: application/x-www-form-urlencoded

client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}
&grant_type=refresh_token
&refresh_token={REFRESH_TOKEN}

Webhook Fulfillment Intents

Once authorized, your service will receive requests at your fulfillment endpoint. These requests, called "intents," tell your application what action to perform. Use the interactive explorer on the right to see the structure for each intent. All requests are `POST` calls to your fulfillment URL, authenticated with a Bearer token.

Rate Limiting

To ensure API stability for all users, we enforce a rate limit of **10 requests per minute** per access token. If you exceed this limit, you will receive an `HTTP 429 Too Many Requests` response. You can check the returned HTTP headers to manage your request rate programmatically.

Error Codes

Our API uses standard HTTP status codes to indicate the success or failure of a request. A JSON body with more details may also be returned. Use the search box below to quickly filter the error codes.

Security Guidelines

Protecting user data is critical. Please adhere to these security best practices when integrating with our API.

• ✓
  HTTPS Only: All API communication must be over a secure TLS connection.
• ✓
  Protect Client Secret: Your `client_secret` must never be exposed in client-side code like a web browser or mobile app.
• ✓
  Secure Token Storage: Do not persist access tokens. Refresh tokens should be stored securely on your server.
• ✓
  Monitor and Log: Keep logs of API interactions to monitor for errors and suspicious activity.

Sample Code (Python)

Here’s a quickstart example in Python showing how to make a `SYNC` request to the fulfillment endpoint. This demonstrates how to structure the headers and payload for the request.

import requests
import json

ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
FULFILLMENT_URL = "https://api.jasminesmarthomes.com/webhook/fulfilment"

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json"
}

sync_payload = {
    "requestId": "a-random-request-id-123",
    "inputs": [{"intent": "action.devices.SYNC"}]
}

try:
    response = requests.post(
        FULFILLMENT_URL,
        data=json.dumps(sync_payload),
        headers=headers
    )
    response.raise_for_status()
    print(f"Status: {response.status_code}")
    print("Response:", response.json())
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")