Skip to main content

API Authentication

The Spotto API uses API keys for authentication. Keys are scoped to your company and can be configured with specific roles and access restrictions.

Generating an API Key​

To create an API key:

  1. Log in to the Spotto Portal as a company administrator
  2. Navigate to API Keys
  3. Click Create API Key
  4. Provide a name and optional description (e.g., "CI/CD Pipeline" or "Monitoring Integration")
  5. Select the appropriate role permissions
  6. Optionally configure IP or country restrictions
  7. Copy the key immediately - it won't be shown again
Store Your Key Securely

The plaintext API key is displayed only once at creation time. Spotto stores a masked version for display purposes, but the full key cannot be retrieved later. If you lose it, you'll need to rotate or create a new key.

Using Your API Key​

Include your API key in requests using either header format:

curl -X GET "https://api-au.spotto.ai/v1/subscriptions" \
  -H "x-api-key: YOUR_API_KEY"

Replace api-us.spotto.ai with your region's endpoint if you're in Australia or Europe.

Key Configuration​

When creating or updating an API key, you can configure:

SettingDescription
NameA descriptive label for identifying the key
DescriptionOptional notes about the key's purpose
RolePermission level (e.g., Reader, Company Admin)
IP Allow/Deny ListsRestrict access to specific IPs, CIDR ranges, or IP ranges
Country Allow/Deny ListsRestrict access by country (ISO alpha-2 codes)

Key Management​

From the API Keys page in the portal, you can:

  • View keys — See all keys with their masked identifiers, roles, and creation details
  • Update keys — Modify the name, description, role, or access restrictions
  • Rotate keys — Generate a new secret while preserving the key's configuration. The old key is immediately invalidated
  • Revoke keys — Permanently delete a key

Key Rotation​

When you rotate a key:

  1. A new API key secret is generated
  2. The previous key is immediately deleted and stops working
  3. The new plaintext is shown once—copy it before closing the dialog
  4. All other settings (name, role, restrictions) are preserved

Rotation is useful when a key may have been exposed or as part of regular security hygiene.

Access Restrictions​

IP Filtering​

You can restrict API key usage to specific network addresses:

  • Single IP: 192.168.1.100
  • CIDR notation: 10.0.0.0/8
  • IP range: 192.168.1.1-192.168.1.254

Configure allow lists to permit only specific addresses, or deny lists to block known problematic sources.

Country Filtering​

Restrict access based on the request's origin country using ISO alpha-2 country codes (e.g., US, AU, GB). This uses Cloudflare's IP geolocation.

Security Best Practices​

  • Use environment variables — Never hardcode keys in source code
  • Apply least privilege — Assign the minimum role needed for the integration
  • Restrict by IP when possible — If your integration runs from known IPs, add them to an allow list
  • Rotate periodically — Regular rotation limits exposure from undetected leaks
  • Monitor usage — Review your keys and their access patterns regularly
  • Revoke unused keys — Delete keys that are no longer needed

Troubleshooting​

401 Unauthorized

  • Verify the API key is correct and hasn't been rotated or revoked
  • Check that you're using the correct header format (Authorization: ApiKey or x-api-key)
  • Confirm you're hitting the right regional endpoint for your account

403 Forbidden

  • The key's role may not have permission for the requested resource
  • IP or country restrictions may be blocking the request
  • API keys cannot access key management endpoints - use the portal for those operations

Key Not Working After Rotation

  • After rotation, the old key is immediately invalid
  • Update all integrations with the new key value
  • The new key was shown only once at rotation time - if you didn't capture it, rotate again