API Keys

Manage your API keys for programmatic access to Palpable.

Overview

API keys provide full access to your Palpable account via the API. Treat them like passwords:

Never expose API keys in client-side code
Never commit API keys to version control
Use environment variables to store keys
Rotate keys periodically

Creating API Keys

Via Mobile App

Open the Palpable app
Go to Settings > Developer > API Keys
Tap + to create a new key
Enter a descriptive name (e.g., "Production Server")
Copy the key immediately - it won't be shown again

Via API

POST /api/user/keys
Authorization: Bearer pk_existing_key
Content-Type: application/json

{
  "name": "New API Key"
}

Response

{
  "key": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "New API Key",
    "key": "pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
    "createdAt": "2024-01-15T12:00:00Z"
  }
}

Important: The full key value is only returned once, at creation time. Store it securely.

Listing API Keys

GET /api/user/keys
Authorization: Bearer pk_your_key

Response

{
  "keys": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production Server",
      "prefix": "pk_a1b2c3d4",
      "createdAt": "2024-01-01T00:00:00Z",
      "lastUsed": "2024-01-15T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Development",
      "prefix": "pk_x9y8z7w6",
      "createdAt": "2024-01-10T00:00:00Z",
      "lastUsed": null
    }
  ]
}

Only the key prefix is returned for security. The full key cannot be retrieved.

Deleting API Keys

DELETE /api/user/keys
Authorization: Bearer pk_your_key
Content-Type: application/json

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Response

{
  "success": true
}

Warning: Deleting a key is immediate and irreversible. Any applications using that key will stop working.

Using API Keys

Include your API key in the Authorization header of every request:

curl -X GET https://palpable.technology/api/devices \
  -H "Authorization: Bearer pk_your_api_key_here" \
  -H "Content-Type: application/json"

Example: Node.js

const response = await fetch('https://palpable.technology/api/devices', {
  headers: {
    'Authorization': `Bearer ${process.env.PALPABLE_API_KEY}`,
    'Content-Type': 'application/json'
  }
});
 
const data = await response.json();
console.log(data.devices);

Example: Python

import os
import requests
 
response = requests.get(
    'https://palpable.technology/api/devices',
    headers={
        'Authorization': f'Bearer {os.environ["PALPABLE_API_KEY"]}',
        'Content-Type': 'application/json'
    }
)
 
devices = response.json()['devices']

Example: cURL

export PALPABLE_API_KEY="pk_your_key_here"
 
curl -X POST https://palpable.technology/api/devices/command \
  -H "Authorization: Bearer $PALPABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "moduleId": "NeoPixel",
    "tool": "set_color",
    "params": { "r": 255, "g": 0, "b": 128 }
  }'

Key Naming Best Practices

Use descriptive names that indicate:

The environment (Production, Staging, Development)
The application or service using the key
The purpose (CI/CD, Monitoring, Backup)

Examples:

Production API Server
GitHub Actions CI
Home Assistant Integration
Data Analytics Pipeline
Development Local

Security Recommendations

One key per application - Create separate keys for each service or environment
Regular rotation - Rotate keys every 90 days
Monitor usage - Check lastUsed to identify unused keys
Immediate revocation - Delete keys immediately if compromised
Environment variables - Never hardcode keys in source code

# .env file (never commit this!)
PALPABLE_API_KEY=pk_your_secret_key_here

// Load from environment
const apiKey = process.env.PALPABLE_API_KEY;

Webhooks