Skip to main content
SuprSend provides multiple authentication methods, each with different scopes:
  • Workspace Key & Secret → Backend SDK authentication
  • API Keys → REST API authentication per workspace
  • Service Tokens → Management API authentication across workspaces
This guide covers best practices for keeping them secure.

​
1. Workspace Key & Secret

  • Pre-generated for each workspace.
  • Used only with backend SDKs.
  • Safer by design as the Workspace Secret is never transmitted over the network.
Best Practices:
  • Never share Workspace Secrets (not even with SuprSend support).
  • Store them securely in environment variables or a key management system.
  • Rotate the secret via the Management API: PATCH /v1/{workspace}/ws_key/{id}/rotate/. Rotation works on every record, including the default. The key stays the same; only the secret changes.
  • Maintain a separate workspace key/secret for each backend service that authenticates. Use POST /v1/{workspace}/ws_key/ to add records and DELETE /v1/{workspace}/ws_key/{id}/ to remove non-default ones. When one service’s secret leaks, you rotate or delete only that record - the other services keep running.
The workspace secret is returned in plain text on every response from these endpoints (list, detail, create and rotate) - not just once. Do not log the response, do not surface it to browsers, and store the secret only in an environment variable or secrets manager.

​
2. API Keys

  • Used for authenticating REST API requests at the workspace level.
  • Each workspace has its own set of API Keys, isolating staging and production workspaces.
Best Practices:
  • Treat API Keys as sensitive secrets - never expose them in client-side code.
  • Always store keys securely (as environment variables or in a secure vault).
  • Rotate periodically (for example, every 6 months).
  • Rotate immediately if a key is compromised or accidentally exposed.
  • Monitor API usage for anomalies on SuprSend dashboard -> Logs (Requests tab) (unexpected spikes, unauthorized calls).

​
3. Service Tokens

  • Used to authenticate Management APIs.
  • Scoped at the account level, allowing cross-workspace operations (for example, promoting workflows from staging → production).
  • Provide higher privilege than API Keys, so require stricter handling.
Best Practices:
  • Limit use of Service Tokens to CI/CD pipelines and automation - avoid day-to-day manual use.
  • Store them as environment variable or encrypted secrets manager.
  • Rotate on a scheduled basis (every 6–12 months).
  • Rotate immediately if exposed or if a privileged user leaves the team.
  • Maintain strict access control - only admins or automation systems should have access.

​
General Security Guidelines

  1. Never commit keys/tokens to version control (for example, GitHub).
  2. Use environment variables or a Key Management Service (for example, AWS KMS, HCP Vault, GCP Secret Manager).
  3. Follow least privilege principle — share keys only with systems or people that need them.
  4. Set up monitoring & alerts for unauthorized or unusual activity.
  5. Rotate keys/tokens regularly and immediately upon suspected compromise.

​
Rotation Strategy

  • Scheduled Rotation
    • API Keys → every 6 months
    • Service Tokens → every 6–12 months
    • Workspace Secrets → rotate if organizational policy requires
  • Ad-Hoc Rotation
    • Immediately upon exposure (logs, repositories, screenshots)
    • On suspicious activity or abuse
    • When a team member with access leaves