Authentication
HTTP Basic Auth for the Fuxam API v4 — clientId and clientSecret, credential lifecycle, all-or-nothing access, and security best practices.
Every request to the Fuxam API v4 authenticates with HTTP Basic Auth using an integration’s clientId and clientSecret. There is no separate session cookie, OAuth bearer token, or per-request API key header in v4 — the Authorization header is the entire auth surface.
Why it matters
API credentials are institution-level power. A leaked clientSecret lets an attacker read and change the same data your integration can, because v4 does not implement permission scopes on Basic Auth. Solid credential hygiene — creation, storage, rotation, and least exposure — is as important as correct request code.
How it fits
Authentication ties to the product as follows:
- Credentials are created under Organization → API integrations in Fuxam Web.
- The integration acts for the institution, not as a named staff user from User Management.
- After auth succeeds, every request still follows the shared conventions in the Overview (envelope, pagination, errors).
Key concepts
| Term | Definition |
|---|---|
| Integration | A registered API client for your institution. |
| clientId | Public identifier of the integration (the Basic Auth “username”). |
| clientSecret | Confidential secret (the Basic Auth “password”). |
| Basic Auth | Standard Authorization: Basic header with Base64-encoded clientId:clientSecret. |
| All-or-nothing | v4 does not implement API-key permission scopes — authenticated integrations have full integration access. |
How Basic Auth works
Encode credentials as Base64 of the string clientId:clientSecret (no extra spaces):
Authorization: Basic <base64(clientId:clientSecret)>Example with curl (preferred — lets curl encode for you):
curl -sS \
-u "${CLIENT_ID}:${CLIENT_SECRET}" \
-H "Accept: application/json" \
"https://fuxam.app/api/v4/users?limit=1"Manual encoding for debugging:
printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 | tr -d '\n'How to obtain credentials
Sign in to Fuxam Web with an account that can manage organization settings.
Go to Organization → API integrations.
Create a new integration and copy the clientId and clientSecret into your secrets store.
Verify with a simple read such as GET /users?limit=1 before wiring the credentials into production jobs.
For a full first-call walkthrough, see Getting started.
All-or-nothing access
API-key permission scopes are not implemented in v4. Basic Auth is all-or-nothing for the integration:
- There is no documented way to issue a “read-only” API key via scopes.
- Treat every integration as capable of any operation the API exposes to integrations.
- Reduce risk by limiting who can create integrations, isolating credentials per system, and writing clients that only call the endpoints they need.
Rotating and replacing credentials
Plan for rotation the same way you rotate database passwords:
- Create a new integration (or obtain a new secret, if your process replaces the secret on the same integration).
- Update every consumer (CI, middleware, serverless env) to the new credentials.
- Confirm production traffic succeeds with the new pair.
- Retire or delete the old credentials so they can no longer authenticate.
Security best practices
| Practice | Guidance |
|---|---|
| Secret storage | Keep clientSecret in a secrets manager or encrypted env store. Never commit it to git or paste it into tickets. |
| Least privilege (operational) | Even without API scopes, give credentials only to the services that need them; separate integrations per workload. |
| TLS only | Call https://fuxam.app exclusively. Reject redirects to non-TLS URLs in HTTP clients. |
| Log carefully | Log meta.requestId and status codes; never log the Authorization header or raw secret. |
| Rotate on staff change | When someone with access to the secret leaves, rotate credentials. |
| Revoke on leak | If a secret may have been exposed, disable or replace the integration immediately and audit recent traffic. |
Common pitfalls
| Pitfall | What happens | Fix |
|---|---|---|
| Hand-rolled Base64 with newlines | Intermittent 401 |
Strip newlines, or use -u / library Basic Auth |
| Embedding secrets in mobile or browser apps | Anyone can extract them | Call the API only from trusted server-side components |
| Sharing one integration across many teams | Hard to rotate; noisy rate limits | Split by system |
Assuming 403 for unauthorized resources |
v4 never emits 403 for cross-tenant denial |
Expect 404 resource_not_found — see Errors and idempotency |
FAQ
Is there OAuth2 or personal access tokens in v4?
This handbook documents HTTP Basic Auth with integration clientId and clientSecret as the v4 authentication method. Use that pattern unless your institution receives different instructions.
Does each staff user need their own API credentials?
No. Integrations authenticate the institution integration, not an individual User Management account. Staff continue to use Fuxam Web with their own roles; middleware uses the integration credentials.
What status code means bad credentials?
Failed authentication typically returns 401. Distinguishing “bad password” from “unknown client” is not something clients should rely on beyond treating 401 as “fix credentials.”