Skip to content

Authentication and keys

Authenticate every customer API request with a bearer key:

Authorization: Bearer YOUR_API_KEY

Use the key from API Access → API keys. Send it from your server; browser session cookies do not substitute for a bearer key.

Terminal window
curl --fail-with-body \
'https://githoundexplore.com/api/v1/workspaces' \
-H "Authorization: Bearer $GITHOUND_API_KEY"

Set the environment variable through your deployment’s secret manager. Do not paste a real secret into source files, example commands stored in a repository, URLs, or browser JavaScript.

Choose a descriptive name and an expiry of 30, 90, or 365 days. The default is 90 days. Each account can have five active keys, and can create five keys per hour.

The complete secret appears once. It cannot be retrieved later. If you lose it, revoke that key and create a replacement. The key list retains metadata such as name, creation time, expiry, status, and last use; last-use timestamps are updated periodically rather than on every request.

A valid key identifies the account; current access eligibility is checked separately on every request. Pro, eligible verified trials, and eligible existing grants can execute the API. A Free account can manage keys but cannot execute these endpoints.

  • 401 unauthorized: the key is missing, malformed, expired, revoked, or otherwise invalid.
  • 403 premium_required: the authenticated account lacks current eligible access.
  • 503 authorization_unavailable: eligibility could not be established; this is not a definitive denial.

Create a replacement key, update the secret in your integration, verify a request, then revoke the old key in API Access. If all five key slots are occupied, revoke an unused key first.

Revocation prevents new requests. An already-running bounded stream may finish. Revoking and creating keys does not reset account usage or rate limits.

The customer API is server-to-server. Requests carrying an Origin header are rejected, CORS preflight is not supported, and keys cannot be supplied through query parameters. Do not build a browser integration by embedding a secret or suppressing browser protections; place the integration behind your own authenticated server.

Only the workspace-list endpoint accepts a query parameter (cursor). Unexpected or repeated query parameters are rejected. Keep POST bodies bounded and send a known Content-Length; standard JSON requests from curl and most server clients do this automatically.