Integrations

API Keys

API keys authenticate your requests to the Humiris API. Generate keys with specific scopes, rotate them on a schedule, and manage permissions per key.

How to generate an API key

You can generate API keys from the Humiris dashboard or via the API itself (using an existing admin key). Each key is a unique string prefixed with hum_sk_live_ for production or hum_sk_test_ for sandbox environments.

The full key is shown only once at creation time. Store it securely. If you lose a key, you can revoke it and generate a new one.

bash

# Generate a new API key via the API
curl -X POST https://api.humiris.com/v1/api-keys \
  -H "Authorization: Bearer hum_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-backend",
    "scopes": ["agents:read", "agents:write", "email:send", "phone:send"]
  }'

# Response
{
  "id": "key_m4k8x2",
  "name": "production-backend",
  "key": "hum_sk_live_abc123...",
  "scopes": ["agents:read", "agents:write", "email:send", "phone:send"],
  "created_at": "2026-04-06T10:00:00Z"
}

Authentication: Bearer token

Include your API key in the Authorization header of every request as a Bearer token.

bash

# Authenticate a request
curl https://api.humiris.com/v1/agents \
  -H "Authorization: Bearer hum_sk_live_abc123..."

# Using the SDK
import { Humiris } from '@humiris/sdk'

const client = new Humiris({
  apiKey: process.env.HUMIRIS_API_KEY
})

If the key is missing, invalid, or expired, the API returns a 401 Unauthorized response.

Scopes and permissions

Each API key can be restricted to specific scopes. This follows the principle of least privilege: give each key only the permissions it needs.

agents:readList and retrieve agent details

agents:writeCreate, update, and delete agents

email:readRead agent email inboxes

email:sendSend email from agent addresses

phone:readRead SMS inbox and call logs

phone:sendSend SMS and initiate calls

wallet:readView wallet balances and history

wallet:writeSign and send transactions

card:readView card details and transactions

card:writeIssue cards and update controls

computer:readView VPS status and backups

computer:writeExecute commands and manage VPS

webhooks:manageCreate, update, and delete webhooks

api-keys:manageCreate and revoke API keys

Key rotation

Rotate API keys regularly to minimize risk. Humiris supports a graceful rotation workflow: create a new key, deploy it to your application, then revoke the old key. Both keys will work during the transition period.

bash

# List all API keys
curl https://api.humiris.com/v1/api-keys \
  -H "Authorization: Bearer hum_sk_live_..."

# Revoke a specific key
curl -X DELETE https://api.humiris.com/v1/api-keys/key_m4k8x2 \
  -H "Authorization: Bearer hum_sk_live_..."

# Rotation workflow:
# 1. Create a new key with the same scopes
# 2. Deploy the new key to your application
# 3. Verify the new key works
# 4. Revoke the old key

You can also set an expiration date on keys. Expired keys are automatically revoked and will return 401 Unauthorized after the expiration timestamp.

bash

# Create a key with an expiration date
curl -X POST https://api.humiris.com/v1/api-keys \
  -H "Authorization: Bearer hum_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "temp-integration-key",
    "scopes": ["agents:read"],
    "expires_at": "2026-07-01T00:00:00Z"
  }'

Next steps

Use your API key with the Humiris CLI or the MCP integration. Set up Webhooks to receive real-time events. See the API Reference for the full authentication documentation.