Authorization: Bearer header: a SmartAlex API key or an OAuth 2.0 token. Pick whichever your client supports.
API keys
Keys come in two environments:
A key is shown to you once, at creation. We store only a hash, never the raw key, so if you lose it you generate a new one rather than looking it up.
Generating a key
1
Open the Developer Portal
Go to /developers and open the API Keys tab.
2
Create a key
Click Create API Key, choose the environment (live or test) and the scope, and copy the key immediately.
3
Store it securely
Put it in your client config or a secrets manager. You won’t see it again.
Key generation requires the Power Tools add-on and a super-admin role on the workspace. If you don’t see the Developer Portal, check both.
Scopes
A key without
write that calls a write tool gets a 403, so scope your keys to what each client needs.
OAuth 2.0
For hosted clients, connect by URL and authorise in your browser, no key to copy. The server implements the standard discovery flow, so a compliant client sets itself up automatically: Under the hood:- Protected-resource metadata (RFC 9728) is served at
/.well-known/oauth-protected-resource, so the client discovers where to authenticate. - Authorization-server metadata (RFC 8414) is served at
/.well-known/oauth-authorization-server, advertising the authorize and token endpoints, dynamic client registration, and PKCE (S256, required). - A missing or invalid token returns
401with aWWW-Authenticateheader pointing back to the metadata, which is how the client knows to start the flow.
Rate limits
Over the limit returns
429 with a Retry-After header and X-RateLimit-* headers; well-behaved clients back off automatically. If you drive the REST API directly with an sa_ key, that path has its own per-key limit (default 60 / min, adjustable when you create the key).
Local install (npm)
Set an API key for a stdio client.
Error reference
Every auth and rate-limit error, with fixes.