Integration
The Naffes CRM REST API: connect your systems with a Bearer token
Naffes CRM exposes a REST API that accepts Authorization: Bearer and supports list, read, create, update and delete on CRM records, plus search, import, export and associations, all with the permissions of the token's user.
What you build with it
The API is the route when no ready-made connector fits: an ERP that updates deal amounts nightly, an internal portal that creates contacts, a scheduled job that pulls open deals into a BI dashboard. Pair it with outgoing webhooks so your system hears about changes as they happen instead of polling.
| Operation | Request |
|---|---|
| List records | GET /api/contacts, /api/companies or /api/deals |
| Read one | GET /api/deals/{id} |
| Create | POST /api/contacts |
| Update | PUT /api/deals/{id} |
| Delete | DELETE /api/contacts/{id} |
| Global search | GET /api/search |
| Search one type | GET /api/deals/search |
| CSV import | POST /api/contacts/import/upload, then POST /api/contacts/import/{id} |
| Export | POST /api/deals/export |
| Associate records | PUT /api/associations/deals/{id} |
Getting a token and making a first call
Check API access
API access is switched on for everyone who signs up or accepts an invitation. Users who have it see an API Tokens tab under Settings > Personal > My connections.
Create a named token
Click New token, name it after the system that will use it, and create it.
Get the token value
Known issue in the current build: the screen does not display the new token value. Until it is fixed, get a Bearer token from POST /api/token with email, password and device_name. If 2FA is on, the response returns a challenge_token to send with your authenticator code to /api/token/2fa-challenge. The API token guide has a worked example.
Send the first request
Put the token in Authorization: Bearer with Accept: application/json, and start with a read such as listing contacts.
Pick the workspace if needed
If the user belongs to several workspaces, send the X-Tenant-Slug header with the workspace slug; otherwise the request runs in the workspace the user last used, or the oldest one they joined if none is remembered.
curl -s "$NAFFES_HOST/api/deals" \
-H "Authorization: Bearer $NAFFES_TOKEN" \
-H "Accept: application/json"Permissions and token lifecycle
- A token carries its user's full permissions. Whatever the user can see or change in the app, by role and scope, the API can too.
- 14-day default expiry. Plan for renewal in your integration.
- Instant revocation. Under Settings > My Account > Sessions & Security you see tokens and sessions with last use, and revoke one or all. Tokens of a suspended user stop working immediately.
- Rate limit. 600 requests a minute per user by default.
- Direction. Your system reads from and writes to Naffes; for change notifications without polling, add outgoing webhooks.
Practical tip: create a dedicated integration user with a custom role that holds only what the integration needs, for example read and edit deals but not delete, and issue the token as that user. The user counts toward your plan's seats.
What the API does not offer yet
- No scoped tokens. There are no read-only or per-resource tokens; a restricted integration user is the workaround.
- No published OpenAPI spec and no official SDKs.
- No OAuth for third-party apps. The OAuth Apps screen issues a client ID and secret, but there is no authorization or token endpoint yet.
- Admins cannot switch API access off per user. It is on for everyone, and only the platform operator can change it.
- The token screen does not show new tokens today, as noted in the setup steps.
Questions
Questions 4
How long does a token last?
14 days by default, after which you need a new one. You can revoke it earlier at any time under Sessions & Security.
Can a token reach all workspace data?
Only what its user can reach. That is why integration tokens are best issued from a dedicated user with a narrow role.
Why can't I see my token after creating it?
It is a known issue in the current token screen. Use POST /api/token to get a Bearer token until it is fixed.
Is there a request limit?
Yes, 600 requests a minute per user by default. Batch large syncs, and use import and export for big files.