Authentication: API Keys, Tokens & Best Practices

Authentication

SendPromptly uses bearer tokens scoped to a project environment. Tokens identify both your project and the environment receiving traffic.

Header format

1

Authorization: Bearer sp_{env}_{32_random_chars}

Example:

1

Authorization: Bearer sp_prod_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Required ingestion headers

• Authorization
• Idempotency-Key
• Content-Type: application/json

Idempotency-Key is required for safe retries and duplicate protection.

Security best practices

• Use separate tokens for dev, stage, and prod.
• Store tokens in a secret manager, never in source control.
• Restrict usage to backend services; do not expose tokens in browsers or mobile apps.
• Rotate tokens on a regular schedule and after any suspected leak.

Rotation workflow

1. Create a new token in the target environment.
2. Deploy backend changes to use the new token.
3. Verify successful ingestion and delivery.
4. Revoke the old token after confirmation.

Common authentication failures

• 401 unauthorized: token missing, malformed, revoked, or environment mismatch.
• 409 idempotency_conflict: same idempotency key reused with a different payload.

Hardening checklist

• Add request signing and outbound allowlists in your infrastructure where possible.
• Log token fingerprint metadata internally, not full token values.
• Alert on auth failures by environment to detect misconfiguration early.

For complete request examples, see Getting Started and Event Ingestion.