Documentation
API authentication
Authenticate browser sessions and programmatic clients without crossing workspace boundaries.
Upstream uses a different credential for each trust boundary. Authentication never replaces repository authorization.
Authentication matrix
| Credential | Used by | Where it works |
|---|---|---|
| None | Public clients | Public forge GET routes |
| Browser session | upstream.codes | Public contributor mutations and the developer browser API |
| CLI session | upstream | Dedicated repository, workspace, Change Request, and ruleset routes on the Coline control plane |
| Workspace API token | External services | Endpoints that explicitly declare a scope, currently including external checks |
| Git credential or SSH key | Git clients | Clone, fetch, and push through git.coline.app |
Browser sessions
upstream.codes establishes a local session through the shared Coline authentication authority. Browser mutations must pass the same-origin CSRF check. Do not automate the product by copying a browser cookie into another service.
CLI sessions
upstream auth login creates a browser challenge and returns a separate revocable CLI token after approval. It is not the browser cookie and is not a workspace API token. Read CLI authentication for the full flow.
Workspace API tokens
Send workspace API tokens in the Authorization header:
Authorization: Bearer <token>
The token's workspace is an authorization boundary. A valid token cannot address data in another workspace. Tokens only authorize routes that explicitly accept their scopes; they do not unlock the developer browser API.
Scopes
The wider Coline API scope vocabulary includes workspace and file reads, task-board reads and writes, notification writes, administrative reads, and upstream.checks.write for external check reports. Of those, upstream.checks.write is the currently documented Upstream forge automation scope.
Read the current vocabulary from protected-resource metadata or the x-api-scopes field in OpenAPI.
Git is separate
Workspace API tokens and CLI sessions do not replace ordinary Git authentication. Git HTTPS uses a repository-scoped col_git_... secret through HTTP Basic authentication; SSH uses an account public key. The CLI credential helper performs that exchange automatically.