Token Auth

Token auth lets your backend mint short-lived MQTT credentials for your end users. The token service returns an OAuth-style response that includes a ready-to-use MQTT username and password tied to a specific user email.

How It Works

1. Your backend calls POST /v2/tokens/create with your organization ID and secret key
2. The token service returns temporary MQTT credentials scoped to the user's email
3. Your device or client connects using those credentials
4. When the token's TTL elapses, the connection is closed and the credentials stop working

Enabling Token Auth

1. Navigate to Dashboard → Authentication
2. In the Other Methods section, find Token-Based Auth
3. Toggle the switch On

Creating Tokens

Tokens are minted using your organization's secret key (sk_ prefix; legacy cs_ keys still work). Get one from Dashboard → API Keys.

curl -X POST https://api.cloudsignal.app/v2/tokens/create \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_k7xm4pqr2n5t",
    "secret_key": "sk_your_secret_key",
    "user_email": "user@example.com"
  }'

Response:

{
  "access_token": "tkn_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "mqtt_credentials": {
    "username": "abc123@org_k7xm4pqr2n5t",
    "password": "tkn_..."
  },
  "token_id": "uuid",
  "user_email": "user@example.com",
  "provider": "cloudsignal",
  "expires_at": "2026-03-27T14:00:00Z",
  "refresh_recommended_at": "2026-03-27T13:54:00Z"
}

Use mqtt_credentials.username and mqtt_credentials.password directly with any MQTT client. The password is also available as access_token for OAuth-style consumers.

Refreshing Before Expiry

Refresh at refresh_recommended_at (roughly 10% before expires_at). The response contains the same shape, with a new password.

curl -X POST https://api.cloudsignal.app/v2/tokens/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "token_id": "uuid-from-create",
    "current_token_password": "tkn_..."
  }'

Token Lifecycle

• TTL: Configurable per organization (default 60 minutes; see Dashboard → Auth Providers → Token-Based Auth → Configuration)
• Refresh: Recommended at refresh_recommended_at; the old password is invalidated the moment a refresh succeeds
• Expiry: Expired tokens are disabled within 5 minutes and deleted after 1 hour
• Isolation: Tokens are scoped by user email within an organization - a second create for the same email replaces the prior token when replace_existing is true (default)

When to Use

• End-user apps where each customer's device gets its own short-lived MQTT credentials
• IoT device fleets managed by a central backend
• Environments where you don't want persistent credentials on devices