Key types

CloudSignal uses two types of API keys to support different security requirements: publishable keys and secret keys.

Publishable keys (`pk_`)

Publishable keys are designed to be safe for use in client-side code.

Characteristics

Aspect	Detail
Prefix	`pk_` (for example `pk_live_abc123...`)
Visibility	Safe to expose in browsers, mobile apps, public repos
Permissions	Limited to read-only and public operations
Use case	Client-side API calls

What publishable keys can do

Operation	Allowed
REST bridge publish (with ACL)	Yes
Read public organization info	Yes
Token exchange (with auth provider)	Yes
Create or delete clients	No
Modify ACL rules	No
Access billing	No

Example usage

// Safe to use in browser code
const CLOUDSIGNAL_PK = 'pk_live_abc123xyz';

// REST bridge - publish with client permissions
await fetch('https://rest-publisher.cloudsignal.app/publish', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${CLOUDSIGNAL_PK}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    topic: 'agents/agent-01/state',
    payload: { status: 'idle' },
  }),
});

Even though publishable keys are safe to expose, ACL rules still apply. A publishable key can only access topics the associated user has permission for.

Secret keys (`sk_`)

Secret keys provide full access to your CloudSignal organization.

Characteristics

Aspect	Detail
Prefix	`sk_` (for example `sk_live_def456...`)
Visibility	Never expose. Server-side only.
Permissions	Full access to all API operations
Use case	Server-side automation, admin tasks

What secret keys can do

Operation	Allowed
All publishable key operations	Yes
Create or delete clients	Yes
Modify ACL rules	Yes
Manage auth providers	Yes
Token exchange (server-side)	Yes
Access organization settings	Yes

Example usage

// Server-side only - never expose this key
const CLOUDSIGNAL_SK = process.env.CLOUDSIGNAL_SECRET_KEY;

// Create a new MQTT client programmatically
const response = await fetch('https://api.cloudsignal.io/v2/clients', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${CLOUDSIGNAL_SK}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: 'agent-001',
    password: generateSecurePassword(),
  }),
});

Security critical: secret keys should only exist in server-side code, environment variables, or secure secret managers. Never commit them to version control or expose in client-side code.

Choosing the right key

Pick by where the code runs:

If your code runs in a browser or mobile app, use a publishable key (pk_).
If your code runs server-side (Node.js, Python, Go, automation, CI/CD), use a secret key (sk_).

Common scenarios

Scenario	Key type	Reason
React app publishing events	`pk_`	Client-side, limited scope
Node.js backend creating clients	`sk_`	Server-side, admin operation
Mobile app token exchange	`pk_`	Client-side, user-scoped
CI/CD pipeline managing ACLs	`sk_`	Automation, admin operation
Browser-based dashboard	`pk_`	Client-side, user context
Webhook handler	`sk_`	Server-side, system operation

Security best practices

For publishable keys

Practice	Why
Use ACL rules	Limit which topics the key can access
Scope to user context	Pair with user authentication
Rate limit	Implement client-side rate limiting
Monitor usage	Watch for unusual patterns

For secret keys

Practice	Why
Environment variables	Store in `process.env`, not code
Secret managers	Use AWS Secrets Manager, HashiCorp Vault, and similar tools
Rotate regularly	Change keys every 90 days
Minimal exposure	Only give access to services that need it
Audit logs	Monitor API usage for anomalies

Environment variable example

# .env file (never commit this)
CLOUDSIGNAL_PK=pk_live_abc123xyz
CLOUDSIGNAL_SK=sk_live_def456uvw

# Access in code
const publishableKey = process.env.CLOUDSIGNAL_PK;
const secretKey = process.env.CLOUDSIGNAL_SK;

Key identification

You can identify key types by their prefix:

pk_live_abc123xyz...  -> Publishable (live/production)
pk_test_abc123xyz...  -> Publishable (test/development)
sk_live_def456uvw...  -> Secret (live/production)
sk_test_def456uvw...  -> Secret (test/development)

Test keys (_test_) work with test or sandbox environments and won't affect production data.

Next steps

Create and manage keys
Set up auth providers - Use keys for token exchange
REST bridge guide - Publish via HTTP

On this page