---
icon: key
title: Authentication
description: 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

```mermaid
flowchart LR
  Admin[Organization admin] --> Create[API integrations]
  Create --> Creds[clientId and clientSecret]
  Creds --> Header[Authorization Basic]
  Header --> API[Fuxam API v4]
  API --> Data[Institution data]
```

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](/docs/fuxam-web/base/user-management).
- After auth succeeds, every request still follows the shared conventions in the [Overview](/docs/api/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):

```http
Authorization: Basic <base64(clientId:clientSecret)>
```

Example with `curl` (preferred — lets curl encode for you):

```bash
curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/users?limit=1"
```

Manual encoding for debugging:

```bash
printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 | tr -d '\n'
```

:::note
Always send credentials over **TLS** (`https://`). Never send Basic Auth on plain HTTP.
:::

## How to obtain credentials

1. Sign in to Fuxam Web with an account that can manage organization settings.

2. Go to **Organization → API integrations**.

3. Create a new integration and copy the `clientId` and `clientSecret` into your secrets store.

4. 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](/docs/api/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.

:::warning[No scopes in v4]
Do not assume a missing scope will block a write. If your client can authenticate, enforce least privilege in **your** code and deployment policy.
:::

## Rotating and replacing credentials

Plan for rotation the same way you rotate database passwords:

1. Create a **new** integration (or obtain a new secret, if your process replaces the secret on the same integration).
2. Update every consumer (CI, middleware, serverless env) to the new credentials.
3. Confirm production traffic succeeds with the new pair.
4. Retire or delete the old credentials so they can no longer authenticate.

:::tip
Use **one integration per consuming system** (for example SIS sync vs. BI export). That way you can rotate or revoke one client without interrupting others, and `meta.requestId` plus rate-limit budgets stay easier to attribute.
:::

## 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](/docs/api/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."

## Related pages

**[Getting started](/docs/api/getting-started)**

First authenticated request end to end.

**[Errors and idempotency](/docs/api/errors-and-idempotency)**

Problem details, 401 vs 404, and rate limits.

**[API overview](/docs/api/overview)**

Shared conventions for every endpoint.

**[Recipes](/docs/api/recipes)**

Practical patterns that assume correct auth.
