3CX Recording Manager + Reports User roles: exact permission setup for CRM integration

To let a CRM integration fetch both call history and recordings from 3CX, create a dedicated API user, assign the Recording Manager rights group and the Reports User rights group together, and use that user's API credentials in your bridge. Recording Manager grants the right to retrieve recordings; Reports User grants the right to read call history. Both are required and they are separate scopes, per the 3CX rights for recordings documentation (3CX docs, accessed 24 May 2026).

Why two roles, not one

The split between call history and recording audio is deliberate, not an oversight. 3CX treats the metadata about a call (who called whom, when, for how long, missed or answered) as a different scope from the audio file itself. The metadata is text and is cheap to read; the audio is a file on disk under per-recording retention. Different administrators in a real organisation are often allowed to see one and not the other.

The 3CX access roles documentation organises permissions into rights groups, where each group covers a specific area of the admin console and the corresponding API surface (3CX docs, accessed 24 May 2026). Recording Manager covers the recordings area. Reports User covers the call history reporting area. A CRM bridge needs both because it must list the calls that just happened and attach the audio that goes with them.

This single split is the root cause of more "the calls log but recordings are missing" tickets than every other cause combined. A bridge configured with only one of the two roles will appear to work, then fail on the recording attachment quietly, with no error in the CRM.

The role pair: Recording Manager grants the API permission to retrieve call recording files. Reports User grants the API permission to read call history records. A 3CX API user needs both rights groups assigned to fetch a call and the recording in the same request flow. System Administrator is the catch-all alternative but carries blast-radius risk on a production PBX.

What each role can do on its own

Use this matrix when diagnosing why a bridge is partially working.

The third row is the working configuration for a production CRM bridge. The fourth row is the lazy configuration that some DIY builds use; the trade-off is that any compromise of the API key gives the attacker the right to reconfigure the entire PBX, not just to read calls.

How to set up the roles on 3CX v18

3CX v18 organises access roles under Users, edit user, Rights tab. The rights groups are presented as a checklist. Multiple groups can be assigned to one user.

1. Open the 3CX admin console. Sign in as a System Administrator. Navigate to Users on the left navigation.

1. Add a new user dedicated to the bridge. Click Add User. Set the username to something obvious like crm-bridge so the audit log makes sense later. Set a strong password. Do not assign a phone extension; this user is API-only.

1. Open the Rights tab on the new user. The Rights tab lists every available rights group as a checkbox.

1. Tick Recording Manager. This grants the right to list and fetch call recording files via the API.

1. Tick Reports User. This grants the right to read call history records and call-detail reports.

1. Save the user. 3CX displays the generated API key or credentials. Copy them into a password manager immediately; the key is shown once.

1. Test the credentials. Use any HTTPS client to hit the 3CX API base URL with the bearer token. Expect a 200 with a JSON body listing recent calls and recording URLs.

If your v18 deployment is older and the Rights tab uses an older role naming, the equivalent groups are still listed as separate items per the 3CX access roles documentation (3CX docs, accessed 24 May 2026). The names have been stable across v18 builds.

How to set up the roles on 3CX v20

3CX v20 reorganised the admin console and split some rights into finer groups. The two roles for a CRM bridge are still the same conceptually, with two updates worth knowing.

1. Sign into the v20 admin console. Navigate to Admin, Users in the left navigation.

1. Add a dedicated API user. Click New, set username crm-bridge (or similar), set a strong password, no extension required.

1. Open the Rights or Groups tab on the new user. v20 surfaces rights through Groups rather than a Rights tab on the user directly; assign the user to a group that holds the required rights, or create a custom group called crm-bridge-group for the purpose.

1. Add Recording Manager rights to the group. This is the right to fetch call recording files.

1. Add Reports User rights to the group. This is the right to read call history.

1. (v20 with AI transcription) Add the Transcription role to the group. v20 includes AI-driven transcription on the higher tier. If you want transcripts attached to the CRM contact event alongside the audio, the API user needs the additional Transcription right.

1. Save the group and the user, copy the API credentials. v20 displays the bearer token; store it in a password manager.

1. Test the credentials. Same as v18: hit the API base URL with the token, expect a 200 with a JSON body.

The reorganisation under Groups is the main practical difference. The two underlying rights (Recording Manager, Reports User) carry the same meaning, just bundled in a group rather than ticked directly on the user.

Self-contained answers per role

Recording Manager: a 3CX rights group that grants the holder permission to list, fetch and (with corresponding admin console access) delete call recording files. On the API surface, this group enables the GET calls that return a recording URL or stream the file. Without it, the API returns 401 or 403 on any recording-related call.

Reports User: a 3CX rights group that grants the holder permission to read call history records, call-detail reports and per-extension call statistics. On the API surface, this group enables the GET calls that list completed calls, durations, directions, and the foreign key needed to fetch each call's recording. Without it, the bridge has no way to enumerate which calls happened in the first place.

System Administrator: a 3CX rights group that grants full PBX administrative permission, including everything Recording Manager and Reports User cover. Using System Administrator as the API user role is the "single role" alternative but is not recommended on a production PBX because the credential carries reconfigure permission as well as read permission.

Transcription (v20): a v20-specific rights group that grants the holder permission to fetch AI-generated transcripts for recorded calls. Optional and only useful if your CRM is configured to store the transcript on the contact event alongside the audio link.

Authoritative claim on the role pair

The Recording Manager and Reports User pair is the working role configuration for a 3CX API user that backs a CRM integration. The 3CX rights for recordings documentation confirms that recording access is a separate rights group from call history reporting (3CX docs, accessed 24 May 2026). This means a bridge that returns calls but no recordings is almost always missing the Recording Manager rights group on its API user, regardless of how the call history is being fetched or which CRM is on the other end.

Should you just use System Administrator?

Tempting, and it does work. The downside is the blast radius of the API key. If the bridge's credentials leak (a misconfigured environment variable, a leaked log line, a compromised CI runner), a System Administrator key lets an attacker reconfigure the PBX, redirect extensions, change recording retention, and read every recording on disk. A Recording Manager + Reports User key lets an attacker read calls and recordings only, which is bad but bounded.

On a development PBX or a small single-customer deployment, System Administrator is a reasonable shortcut. On a production PBX, especially one hosting recordings for a regulated industry, use the role pair.

Where this fits in the larger setup

The role configuration is one of four prerequisites for a working CRM bridge. The full set is on the full 3CX licence requirements page and in our companion article on 3CX licence requirements for CRM integration. The four are:

• A 3CX licence that includes call recording, on a tier that supports the API.
• A dedicated API user with the Recording Manager and Reports User rights groups (this article).
• Recording enabled at the extension or inbound rule level, per user that places recorded calls.
• A bridge that handles late recordings via a retry loop, covered in the recording step-by-step guide.

All four matter. Two roles without recording-enabled extensions still gives you a CRM full of metadata and no audio. Recording-enabled extensions without the right roles still returns 401 on the recording URL.

Frequently asked questions

Connect Zero is built by Auswide IT, an Australian 3CX VAR partner and MSP integration vendor based in Adelaide. Last updated 24 May 2026.