Skip to content
Documentation

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.

  1. Open API Keys.
  2. Choose a name that identifies the workload and environment.
  3. For each service, choose an access level, then narrow it to only the scopes the workload needs.
  4. Add an IP allowlist when the workload has stable outbound addresses.
  5. 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.

Authorization: Bearer YOUR_API_KEY

For shell examples, keep the value in an environment variable:

Terminal window
curl --fail-with-body \
--header "Authorization: Bearer $CHAMPREP_TOKEN" \
https://api.champrep.com/v1/auth/whoami

Do not put a key in a URL, query parameter, frontend JavaScript bundle, mobile application, log line, or analytics event.

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.

ServiceReadWriteAdmin
Drivedrive:readdrive:write, drive:delete—
Docsdocs:read, docs:exportdocs:write, docs:share, docs:delete—
Sheetssheets:read, sheets:exportsheets:write, sheets:share, sheets:delete—
Notesnotes:readnotes:write—
Calendarcalendar:readcalendar:write—
Contactscontacts:readcontacts:write—
Workwork:readwork:write, work:delete—
Formsforms:readforms:write—
Invoiceinvoice:readinvoice:write, invoice:send, invoice:delete—
Org Chartscharts:readcharts:write, charts:delete—
Learncourses:readcourses:write—
School LMSNot available by API key yet
ServiceReadWriteAdmin
Mailmail:readmail:write, mail:send—
Chatchat:readchat:write—
Meetmeet:readmeet:write—
RTCComing soon. RTC uses its own project API keys
ServiceReadWriteAdmin
CHAMPREP Codecode:read_api, code:read_repository, code:read_registry, code:read_package_registrycode:write_repository, code:write_registry, code:write_package_registrycode:api; opt-in code:admin_mode
CHAMPREP QAqa:readqa:write—
Runner Farmrunner_farm:readrunner_farm:write—
CLI—cli:use—
CHAMPREP AI—ai:chat; opt-in ai:actions, ai:agent—
ServiceReadWriteAdmin
Businessbusiness:read—business:manage
Billingbilling:read—billing:manage
Developer APIapi:read—api:manage, webhooks:manage
Profileusers:read——

Platform administration is never available to an API key; it needs a signed-in administrator.

  • 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:api is full read and write access to everything your account can reach in Code, so it sits at the Admin level; prefer the narrower read_ and write_ scopes. Code administration endpoints need a key that holds code:admin_mode by name, and an account that is a Code administrator.
  • Runner Farm. runner_farm:write registers 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:write or sheets:write can edit content but cannot share, purge, or export it.
  • CHAMPREP AI. ai:agent lets the CLI AI agent use local tools and includes ai:chat. ai:actions approves or rejects actions that the AI proposes in your CHAMPREP services, and nothing else.

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.

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 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.

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.

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.