Authentication and API keys
The API Gateway accepts scoped CHAMPREP API keys for server integrations and automation. Browser-based account sessions are used to manage keys, but a custom integration should authenticate its service requests with an API key.
Create a key
Section titled “Create a key”- Open API Keys.
- Choose a name that identifies the workload and environment.
- For each service, choose an access level, then narrow it to only the scopes the workload needs.
- Add an IP allowlist when the workload has stable outbound addresses.
- Copy the key once and store it in a secret manager or keychain.
Do not create one broadly scoped key for every application. Separate keys make rotation, audit review, and incident response safer.
Send the credential
Section titled “Send the credential”Authorization: Bearer YOUR_API_KEYFor shell examples, keep the value in an environment variable:
curl --fail-with-body \ --header "Authorization: Bearer $CHAMPREP_TOKEN" \ https://api.champrep.com/v1/auth/whoamiDo not put a key in a URL, query parameter, frontend JavaScript bundle, mobile application, log line, or analytics event.
Scope catalog
Section titled “Scope catalog”The API Keys screen groups services into four areas: Workspace, Communication, Developer, and Admin. For each service, choose an access level, then add or remove individual scopes if the workload needs something narrower:
- None: the key cannot use the service.
- Read: the scopes in the Read column.
- Read & write: Read plus the scopes in the Write column.
- Admin: everything above plus the scopes in the Admin column, for the services that have one.
Scopes marked opt-in are never selected by a level. Tick them by name. A service that your plan does not include is shown locked, with a link to upgrade. The screen always shows the catalog that is currently live.
Workspace
Section titled “Workspace”| Service | Read | Write | Admin |
|---|---|---|---|
| Drive | drive:read | drive:write, drive:delete | — |
| Docs | docs:read, docs:export | docs:write, docs:share, docs:delete | — |
| Sheets | sheets:read, sheets:export | sheets:write, sheets:share, sheets:delete | — |
| Notes | notes:read | notes:write | — |
| Calendar | calendar:read | calendar:write | — |
| Contacts | contacts:read | contacts:write | — |
| Work | work:read | work:write, work:delete | — |
| Forms | forms:read | forms:write | — |
| Invoice | invoice:read | invoice:write, invoice:send, invoice:delete | — |
| Org Charts | charts:read | charts:write, charts:delete | — |
| Learn | courses:read | courses:write | — |
| School LMS | Not available by API key yet |
Communication
Section titled “Communication”| Service | Read | Write | Admin |
|---|---|---|---|
mail:read | mail:write, mail:send | — | |
| Chat | chat:read | chat:write | — |
| Meet | meet:read | meet:write | — |
| RTC | Coming soon. RTC uses its own project API keys |
Developer
Section titled “Developer”| Service | Read | Write | Admin |
|---|---|---|---|
| CHAMPREP Code | code:read_api, code:read_repository, code:read_registry, code:read_package_registry | code:write_repository, code:write_registry, code:write_package_registry | code:api; opt-in code:admin_mode |
| CHAMPREP QA | qa:read | qa:write | — |
| Runner Farm | runner_farm:read | runner_farm:write | — |
| CLI | — | cli:use | — |
| CHAMPREP AI | — | ai:chat; opt-in ai:actions, ai:agent | — |
| Service | Read | Write | Admin |
|---|---|---|---|
| Business | business:read | — | business:manage |
| Billing | billing:read | — | billing:manage |
| Developer API | api:read | — | api:manage, webhooks:manage |
| Profile | users:read | — | — |
Platform administration is never available to an API key; it needs a signed-in administrator.
Notes on specific scopes
Section titled “Notes on specific scopes”- CHAMPREP Code. Each
code:scope matches the personal access token scope of the same name in CHAMPREP Code, and Code checks it on every endpoint.code:apiis full read and write access to everything your account can reach in Code, so it sits at the Admin level; prefer the narrowerread_andwrite_scopes. Code administration endpoints need a key that holdscode:admin_modeby name, and an account that is a Code administrator. - Runner Farm.
runner_farm:writeregisters and manages runners, pools, and connections. It never buys credits or changes payment settings, and it never issues, replaces, or tests a connector secret or runner token. Those actions need a signed-in person. - Docs and Sheets. Sharing (collaborators, link sharing, publication),
permanent deletion or purge, and export each need their own scope. A key
with only
docs:writeorsheets:writecan edit content but cannot share, purge, or export it. - CHAMPREP AI.
ai:agentlets the CLI AI agent use local tools and includesai:chat.ai:actionsapproves or rejects actions that the AI proposes in your CHAMPREP services, and nothing else.
The wildcard scope
Section titled “The wildcard scope”The wildcard scope * (full access) covers every service your plan includes,
including CHAMPREP Code, Runner Farm, and Docs. CHAMPREP Code treats it as
code:api, which is full read and write access. It does not include
ai:agent or code:admin_mode; those must always be selected by name.
Reserve the wildcard for tightly controlled administrative integrations, and narrow existing full-access keys if they do not need the newer services. A scope permits a category of action; it does not override plan, role, organization, or resource permissions.
Key lifecycle
Section titled “Key lifecycle”Rotate
Section titled “Rotate”Create or regenerate a replacement key, deploy it, confirm the workload is using it, and then revoke the previous key. Avoid a rotation that leaves an unattended workload with no valid credential.
Revoke
Section titled “Revoke”Revoke a key immediately if it is exposed, copied to an untrusted system, or no
longer belongs to an active workload. A revoked key should return 401 and
must not be retried indefinitely.
Review
Section titled “Review”Regularly review key names, scopes, IP restrictions, last-used information, and audit activity. Delete unused keys instead of keeping them for a possible future script.
Browser login and CLI login
Section titled “Browser login and CLI login”champrep auth login uses a browser approval flow for a person at a terminal.
champrep auth token stores a scoped API key for automation. The CLI protects
stored credentials with the operating-system keychain and sends all networked
commands through the Gateway.
See CLI authentication and API keys for CLI automation for those workflows.