Getting Started
Authentication
ContractHQ supports two authentication methods: API Keys for machine-to-machine access and OAuth 2.0 for interactive sessions.
API Keys
API keys are the simplest way to authenticate automated workflows. Each key is tied to specific scopes and can be revoked at any time.
Creating an API Key
- Navigate to Settings → API Keys in the dashboard.
- Click Generate New Key.
- Choose required scopes.
- Copy the key immediately — it is shown only once.
⚠️
Never commit API keys to source control. Use environment variables or a secrets manager.
Using an API Key
terminal (curl)
curl -X GET https://api.contracthq.io/v1/contracts \
-H "Authorization: Bearer chq_live_xxxx"terminal (CLI)
contracthq auth login --token chq_live_xxxx
# ✔ Authenticated as workspace "acme-data"OAuth 2.0
OAuth is used for interactive login. ContractHQ implements the Authorization Code + PKCE flow.
OAuth Flow Summary
- CLI generates a code verifier + challenge (PKCE).
- Opens your browser to the ContractHQ authorisation page.
- You log in and grant the requested scopes.
- Browser redirects to localhost with an authorisation code.
- CLI exchanges the code + verifier for an access token.
- Token is stored in
~/.contracthq/config.json.
💡
For CI/CD, always use API keys — not OAuth tokens. OAuth tokens are intended for interactive sessions only.
Token Scopes
| Scope | Description |
|---|---|
| contracts:read | Read contract definitions from the registry. |
| contracts:write | Create and update contracts. |
| contracts:delete | Delete contracts from the registry. |
| validations:run | Trigger validation runs against a warehouse. |
| validations:read | Read historical validation run results. |
| admin | Full access, including team and billing management. |
Revoking Credentials
Revoke a key from Settings → API Keys → Revoke, or via the CLI:
terminal
contracthq auth revoke --key chq_live_xxxx
# ✔ Key revoked successfully