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 the Palpable App

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

Via API

POST /api/user/keys

const res = await fetch('https://palpable.technology/api/user/keys', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name: 'New API Key' })
})
const { key } = await res.json()
console.log(key.key) // Save this — it won't be shown again

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

const res = await fetch('https://palpable.technology/api/user/keys', {
  headers: { 'Authorization': 'Bearer pk_your_api_key' }
})
const { keys } = await res.json()

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

const res = await fetch('https://palpable.technology/api/user/keys', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer pk_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ id: '550e8400-...' })
})

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:

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)

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

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

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

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