> ## Documentation Index
> Fetch the complete documentation index at: https://docs.githits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API authentication

> Authenticate automated workflows with GitHits API tokens, and use CLI login or the playground for local testing.

All documented API endpoints, including experimental ones, require a GitHits token in the `Authorization` header:

```http theme={null}
Authorization: Bearer <your-token>
```

Replace `<your-token>` in your own environment. Do not put credentials in URLs, source files, screenshots, logs or agent conversations. The raw [OpenAPI contract](https://api.githits.dev/v1/openapi.json) is public and needs no token.

## Use an API token in automation

Create an API token in [your token settings](https://app.githits.com/settings/tokens). Store it in your CI or runtime secret store and supply it in the bearer header. The [quickstart examples](/api/quickstart) expect the token in an environment variable named `GITHITS_API_TOKEN`; the API does not require that variable name.

## Use your CLI login

The existing [GitHits login flow](/authentication) stores OAuth credentials in your system keychain by default. Scripts can capture a usable token with `npx githits@latest auth token`; the CLI refreshes an expired OAuth token when needed. The [quickstart](/api/quickstart) shows command substitution without printing the token.

`GITHITS_API_TOKEN` takes precedence over the CLI's stored OAuth credentials. Check the source safely with:

```bash theme={null}
npx githits@latest auth status
```

See [headless and CI authentication](/guides/headless-ci) for setup. Keep the normal keychain storage unless your environment requires another method; [file storage](/authentication#file-storage-mode) is unencrypted.

Calling the REST API or using the playground does not invoke the CLI's token refresh. If a token expires, obtain a current token through your own login and replace the playground value.

## Use the API playground

Enter the token value, without the `Bearer ` prefix, in the playground's bearer field. The playground adds the `Authorization` header for you. GitHits login is not integrated into this documentation site; enter credentials yourself, outside agent-controlled sessions.

The playground uses your browser to send requests directly to `https://api.githits.dev`. Reading the docs needs no authentication, but sending a request uses your token's access and can perform the work described by the endpoint.

<Warning>
  Playground credentials can survive page reloads and carry across endpoint pages. Use a private browser session on a trusted device and close all private windows when finished. Do not assume the CLI's `logout` command clears browser data. For a regular browser session, remove the documentation site's stored data using your browser's site settings.
</Warning>

If the browser reports a network error without a readable API response, do not paste your token into a bug report. Confirm the request destination and see [browser request errors](/api/errors#browser-request-errors).

## Resolve authentication errors

For `AUTHENTICATION_REQUIRED`, check the bearer header and replace expired or invalid credentials. `TERMS_ACCEPTANCE_REQUIRED` means you must review and accept the applicable terms; follow the [terms acceptance instructions](/authentication#terms-of-service-acceptance). Other access failures are described in [errors](/api/errors).