API Authentication
Definition
The gateway accepts API keys and delegated native-login access tokens on their supported routes. Browser session cookies remain the interactive app path; these credential types are not interchangeable.
API keys
Keys belong to a workspace. Base capability can be read-only, full access or Fieldloop submission. Project restrictions, allowed actions and expiry narrow that capability when supplied.
A new Fieldloop submission key carries that workspace capability. The caller still supplies the Project and source destination, and current access is checked at intake. Previously issued restricted keys retain their restrictions.
Changing access requires issuing the intended credential; renaming a key does not broaden it. Never place values in URLs, source, logs or copied agent tasks.
Delegated login
Native login is scoped to supported External Agents benchmark routes and organization login status. Delegation uses external-agents:read and external-agents:write, plus current project read/manage authorization. It does not provision a user, select a fallback organization or grant every endpoint.
The native client uses authorization-code login with PKCE and an OS credential store. Auth discovery/session routes are distinct from customer operations.
Request headers
Supply the credential as a bearer token. TEAMMATELY_API_KEY is injected by your secret mechanism; configure PROJECT_URL with the quickstart.
curl --fail-with-body \
--header "Authorization: Bearer ${TEAMMATELY_API_KEY}" \
"${PROJECT_URL}/cases?limit=1&offset=0"
Choose the credential
| Operation | Credential boundary |
|---|---|
| Case reads | API key with Project read access |
| Case imports/reference writes | API key with the required write access |
| Fieldloop submission/receipts | Fieldloop capability, destination permission and original-submitter receipt ownership |
| External Agents reads | Authorized API key, or delegated external-agents:read plus Project read access |
| External Agents writes | Authorized API key, or delegated external-agents:write plus Project management access |
For delegated terminal access, follow CLI Authentication. Application ingestion uses an API key without browser login. A read-only MCP tool does not narrow the credential's permission elsewhere.
Access failures
For 401, check the credential's presence, validity and API origin. For 403, check the workspace, Project, capability, restrictions and delegated scope. Organization IP restrictions can apply. Correct access through normal administration.