---
icon: rocket
title: Getting started
description: Create a Fuxam API v4 integration, build Basic Auth, call GET /users, read the response envelope, and paginate your first list.
---

This guide walks you from zero to a working authenticated request against the Fuxam API v4. By the end you will have created an integration, built an `Authorization` header, called `GET /users`, interpreted the `{ data, meta }` envelope, and fetched a second page with a cursor.

**Base URL:** `https://fuxam.app/api/v4`

## Why it matters

A first successful call proves three things at once: your credentials work, your network path to `fuxam.app` is open, and your client correctly parses the shared response shape. Getting those foundations right early prevents hours of debugging when you later add writes, retries, and multi-page sync jobs.

## Before you start

You need:

- Access to your institution's Fuxam Web organization settings so you can create an API integration.
- A terminal with `curl` (or any HTTP client that can send Basic Auth).
- A secure place to store the `clientSecret` — treat it like a password.

Related reading: [Authentication](/docs/api/authentication) for credential security, [Overview](/docs/api/overview) for the full convention summary, and [User Management](/docs/fuxam-web/base/user-management) for how users appear in the product UI.

```mermaid
flowchart LR
  Create[Create integration] --> Auth[Build Basic Auth]
  Auth --> Call[GET users]
  Call --> Read[Read data and meta]
  Read --> Page[Paginate with cursor]
```

## How to create an integration

1. In Fuxam Web, open **Organization → API integrations**.

2. Create a new integration and note the `clientId` and `clientSecret` when they are shown. Store the secret immediately — you will need it for every request.

3. Confirm the integration is active for your institution before making calls. Credentials are institution-scoped; they only see that institution's data.

:::warning[Protect the client secret]
Anyone with `clientId` and `clientSecret` can call the API as your integration. v4 Basic Auth is all-or-nothing — there are no permission scopes. See [Authentication](/docs/api/authentication).
:::

## How to build the Authorization header

HTTP Basic Auth encodes `clientId:clientSecret` as Base64 and sends it in the `Authorization` header:

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

Generate the value with your shell (replace the placeholders):

```bash
CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
AUTH=$(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 | tr -d '\n')
echo "Authorization: Basic $AUTH"
```

:::tip
Prefer letting your HTTP library set Basic Auth from username/password rather than hand-rolling Base64 when you move beyond `curl`. Libraries handle padding and character encoding consistently.
:::

## How to make your first request

List users with `GET /users`. This is a safe read-only call and a good smoke test.

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

Equivalent raw HTTP:

```http
GET /api/v4/users?limit=25 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

A successful response looks like:

```json
{
  "data": [
    { "id": "usr_123", "email": "user@example.com" },
    { "id": "usr_456", "email": "another@example.com" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true,
    "limit": 25
  },
  "meta": {
    "requestId": "req_1700000000000_abc123",
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v4"
  }
}
```

### Reading the envelope

| Field | Role |
|---|---|
| `data` | The resource or list of resources. For lists this is always an array. |
| `pagination` | Present on list responses: `next_cursor`, `has_more`, `limit`. |
| `meta.requestId` | Correlate this response with server logs when troubleshooting. |
| `meta.timestamp` | Server time for the response. |
| `meta.version` | Always `"v4"` on this API. |

Keep `meta.requestId` when you open a support ticket — it is the fastest way to locate the request.

## How to paginate

If `pagination.has_more` is `true`, request the next page with the opaque `next_cursor` value:

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

```http
GET /api/v4/users?limit=25&cursor=eyJpZCI6MTIzfQ== HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

Stop when `has_more` is `false`. Do not invent or edit cursors — they are HMAC-signed and bound to your institution and integration. A bad cursor returns `400` with code `invalid_cursor`.

Full details (including a complete walk-all-pages loop) are in [Pagination and filtering](/docs/api/pagination-and-filtering).

## Checklist after your first call

| Check | Expected |
|---|---|
| HTTP status | `200` |
| Body shape | `data` array plus `meta` (and usually `pagination`) |
| `meta.version` | `"v4"` |
| Auth failure | `401` if credentials are wrong — regenerate or re-copy the secret |
| Empty `data` | Valid if your institution has no matching users yet |

## Best practices for first integrations

- Start with **list reads** (`GET /users`, `GET /courses`) before any create or update.
- Log `meta.requestId` on every response in your integration client.
- Use a modest `limit` (for example `25`) while developing; raise toward `100` only when syncing at scale.
- Store credentials in a secrets manager, not in source control. See [Authentication](/docs/api/authentication).
- When you are ready to write, follow [Errors and idempotency](/docs/api/errors-and-idempotency) and the patterns in [Recipes](/docs/api/recipes).

## Common pitfalls

| Symptom | Likely cause | What to do |
|---|---|---|
| `401` Unauthorized | Wrong `clientId`/`clientSecret`, or mangled Base64 | Re-copy credentials; use `-u` with `curl` instead of hand-encoding |
| Empty `data` array | No matching resources, or unexpected filters | Confirm users exist in [User Management](/docs/fuxam-web/base/user-management) |
| `400` `invalid_cursor` | Cursor reused across integrations or edited | Start a new list from the first page |
| Client parses only `data` | Ignoring `pagination` / `meta` | Model the full envelope in your types |

## FAQ

**Which endpoint should I call first?**

`GET /users` is a reliable smoke test: it is read-only and returns the standard list envelope. Open the [Users](/docs/api/users/users/list-users) reference for the full operation details.

**Do I need a different base URL for staging?**

This handbook documents the production base URL `https://fuxam.app/api/v4`. Use the host and path your institution was given for any non-production environment.

**Can I restrict an integration to read-only?**

v4 Basic Auth is all-or-nothing for the integration — API-key permission scopes are not implemented. Control access by who can create integrations and by what your client code is allowed to call.

## Related pages

**[Authentication](/docs/api/authentication)**

Credentials, rotation, and security practice.

**[Pagination and filtering](/docs/api/pagination-and-filtering)**

Cursors, fields, and filters in depth.

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

Conventions and browse-by-resource index.

**[Users reference](/docs/api/users/users/list-users)**

Generated endpoint reference for users.
