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

# Terminus Hub API Authentication & API Keys

> Learn how to authenticate with the Terminus Hub Public API using Bearer API keys and handle common authentication errors in your integration.

The Terminus Hub Public API uses **API key authentication** exclusively. There is no OAuth flow or session-based login for the Public API. Every request is authenticated by passing your API key in the `Authorization` request header. This makes integration straightforward: generate a key once, store it securely, and include it with every call.

<Note>
  This page covers the Public API only. For browser session login and a side-by-side comparison of both methods, see [Authentication](/authentication).
</Note>

## Creating an API Key

API keys are managed from your Terminus Hub account settings. Navigate to [**Account → API Keys**](/account/api-keys) to generate a new key. Each key is shown only once at creation time. Copy it immediately and store it in a secure location such as a secrets manager or environment variable.

<Note>
  API keys are prefixed with `thub_` to make them easy to identify in logs and configuration files. If a key does not start with `thub_`, it is not a valid Public API key.
</Note>

## Sending the Authorization Header

Include your API key on every request using the `Authorization` header with the **Bearer** scheme:

```http theme={null}
Authorization: Bearer thub_xxxxx
```

Replace `thub_xxxxx` with your actual API key. The header is required for all endpoints. There are no public, unauthenticated routes in the Public API.

## Code Examples

The examples below show how to authenticate in three common environments. Replace `thub_xxxxx` with your API key.

<CodeGroup>
  ```bash curl theme={null}
  curl https://hub.terminus.app/api/v1/workspaces \
    -H "Authorization: Bearer thub_xxxxx" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript (fetch) theme={null}
  const response = await fetch(
    "https://hub.terminus.app/api/v1/workspaces",
    {
      method: "GET",
      headers: {
        Authorization: "Bearer thub_xxxxx",
        "Content-Type": "application/json",
      },
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://hub.terminus.app/api/v1/workspaces"
  headers = {
      "Authorization": "Bearer thub_xxxxx",
      "Content-Type": "application/json",
  }

  response = requests.get(url, headers=headers)
  data = response.json()
  print(data)
  ```
</CodeGroup>

## Authentication errors

When authentication fails, the API responds with HTTP **401** and an `error` object whose `type` is `authentication_error`. For a missing, malformed, or unrecognized key, `code` is `null` and `message` is `Invalid API key`.

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "code": null,
    "message": "Invalid API key",
    "param": null,
    "path": null
  }
}
```

### What causes an authentication error

A `401 authentication_error` is returned whenever the key isn't recognized, most often because the key is missing, was mistyped or truncated, has been revoked, or doesn't begin with `Bearer thub_`. Authentication failures don't carry a finer-grained `code` (it is `null`), so branch on the HTTP status and `error.type` rather than on a code.

<Tip>
  If you are receiving unexpected `authentication_error` responses, confirm the header starts with exactly `Bearer thub_` (note the space), that the key is read from the correct environment variable, and that no extra characters (newlines, spaces) were included when it was stored.
</Tip>

## Security Best Practices

Protecting your API key is critical, because anyone who holds it can make requests on your behalf.

<Warning>
  **Never expose your API key in client-side code.** This includes browser JavaScript, mobile apps, or any code that ships to end users. Always make API calls from your server or a secure backend environment.
</Warning>

* **Use environment variables:** store keys in environment variables (e.g., `TERMINUS_API_KEY`) and read them at runtime rather than hard-coding them in source files.
* **Use one key per integration:** every key carries the same full account access, so create a separate key for each integration. You can then revoke one without disrupting the others.
* **Rotate keys periodically:** regularly cycle your API keys as a precaution, even if there is no known compromise.
* **Never commit keys to version control:** add secrets files to `.gitignore` and audit your repository history if a key was accidentally committed.