Authentication
The Senserity API uses bearer token authentication. API keys are created and managed in Settings > API in the dashboard. Key management is available to organisation owners and admins on Professional and Enterprise plans.
Token format
API keys follow the format:
sns_live_<43-char random body>_<6-char checksum>The sns_ prefix identifies keys as Senserity tokens, enabling automatic detection by secret-scanning tools such as GitHub, GitGuardian, and TruffleHog. The trailing CRC32 checksum allows format validation before any database lookup.
Creating a key
Navigate to Settings > API in the dashboard. Click “Create API key”, give it a name, select the scopes you need, and optionally configure an IP allowlist and expiry period.
The full key is shown exactly once at creation. Copy it immediately and store it securely. Senserity stores only a SHA-256 hash of the key — the original cannot be retrieved later.
Scopes
Each API key is granted a set of scopes that control which operations it can perform. Scopes follow a resource:action naming convention.
| Scope | Grants |
|---|---|
| companies:read | Read watchlist companies, profiles, officers, and filings. |
| companies:write | Add/remove companies, enable/disable monitoring. |
| insights:read | Read insight results, category scores, risk scores, and red flags. |
| insights:run | Trigger on-demand insight runs (consumes credits). |
| reports:read | List reports, read metadata, download PDFs. |
| reports:write | Generate new reports (consumes credits). |
| alerts:read | Read alerts and activity feed, filterable by company. |
| attestation:read | Read attestation campaigns, templates, and responses. |
| attestation:write | Create and send attestation campaigns. |
Granting a scope does not bypass tier or credit checks. Operations that consume credits (such as insights:run and reports:write) still deduct from the tenant's credit allocation.
IP allowlisting
Each API key can optionally be restricted to a set of IP addresses or CIDR ranges. When an allowlist is configured, requests from unlisted IPs are rejected with a 403 response. This is configured during key creation or by editing the key in Settings > API.
Key expiry and rotation
Keys can be set to expire after 30, 60, or 90 days, one year, or never. The default expiry is 90 days. Expired keys are automatically rejected.
To rotate a key, create a new key with the same scopes, update your integration to use the new key, then revoke the old key. Both keys are valid simultaneously during the transition.
Security best practices
- Never commit API keys to source control. Use environment variables or a secrets manager.
- Grant only the scopes your integration needs. A read-only integration should not hold write scopes.
- Rotate keys regularly. Set expiry periods and replace keys before they expire.
- Use IP allowlisting for production integrations running from known infrastructure.
- Revoke compromised keys immediately. Revocation takes effect within seconds.