API keys

An API key authenticates every request to the SimpleCold API. Keys belong to your organization, and every request made with a key is recorded against it, so you can see its usage in the dashboard.

What you can do with a key

• Create a key with a name, a mode and an expiry: 1 day, 1 month, 3 months, 6 months, 1 year or never.
• Choose live or test. Live keys (sc_live_…) run real checks and use credits. Test keys (sc_test_…) run the sandbox: fixed results, no credits. Keys created before modes existed have no prefix and are live.
• Use it as a Bearer token in the Authorization header.
• Edit its name and expiry.
• Disable it to block requests without losing it, and enable it again later.
• Regenerate it to get a new secret value for the same key, keeping its history.
• View its usage and request log.

Keys can't be deleted. To retire a key, disable it.

Pages

• Using your API key: the header format, a key check that uses no credits, and every authentication error.
• Create an API key
• Update an API key
• Enable or disable an API key
• Regenerate an API key

Good practice

• Keep keys on your server. Never put one in front-end code, a mobile app or a public repository.
• Store keys in environment variables or a secrets manager, not in source code.
• Use a separate key for each application or environment, so you can disable one without affecting the others.
• Give keys an expiry where you can. Keys that never expire are a standing risk if they leak.
• If a key may have leaked, regenerate it straight away. The old value stops working immediately.