Authentication
Every request Alderstone sends to your middleware carries a Bearer token in the Authorization header. You generate that token in Alderstone, configure your middleware to validate it, and reject anything that doesn't match. This page covers the key lifecycle and the exact request and response shapes.
How it works
- In the app's integration settings, click Generate API key. Alderstone creates a cryptographically random token with an
ask_prefix. - The key is shown once; copy it immediately and store it in your middleware's secret store. Alderstone retains only a secure hash; the plaintext is never stored in retrievable form.
- Alderstone sends the active key as
Authorization: Bearer <key>on every outbound call to your middleware. - Your middleware compares the incoming token to the stored key and rejects mismatches with 401.
Only one active outbound key exists per integration connection, and Alderstone does not accept customer-provided static tokens; always use a generated key.
Request header
The token arrives on every request. The header name is case-insensitive; the value must be the scheme Bearer, a single space, and a non-empty token.
Validate the header before parsing the body; a request with a missing or malformed header should never reach your ERP translation logic.
Request
{
"schemaVersion": "1"
}
Unauthorized
Return 401 when the Authorization header is missing, malformed, or the token doesn't match the active key. Use the standard error body.
Response
{
"schemaVersion": "1",
"error": "Missing or invalid Authorization header. Use: Authorization: Bearer <token>",
"code": "UNAUTHORIZED"
}
Forbidden
Return 403 when the token is valid but not permitted for the requested operation, for example when a middleware that serves multiple route groups and restricts some of them.
Response
{
"schemaVersion": "1",
"error": "Token is not permitted for this operation.",
"code": "FORBIDDEN"
}
API key management
Keys are managed in the app's integration settings (Settings → Integrations in OrderBridge, Settings → ERP connection in Nudge):
- Generate creates the first key for a connection.
- Rotate revokes the old key and issues a new one atomically. The old token starts returning 401 immediately, so update your middleware configuration right away; in-flight requests signed with the old key will fail.
- Revoke disables outbound authentication entirely until a new key is generated. Use this if a key may have been exposed.
Security best practices
- Serve HTTPS only in production; the Bearer token is the sole shared secret.
- Never log full tokens in your middleware. Alderstone masks tokens in its UI; do the same in your logs.
- Rotate keys on a schedule and whenever team members with access leave.
- Keep ERP credentials in your middleware's secret store, separate from the Alderstone key.
Testing with the sandbox
Use the Developer Sandbox to fire contract requests at your middleware (or the built-in mock) and see pass/fail validation. Sign in with your email to save targets and history. See Test with the sandbox for details.