> ## 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.

# Authentication

> How you sign in to Terminus Hub with email and password (or SSO), and how to authenticate API requests with an account API key.

Terminus Hub has two ways in, for two different jobs. People sign in to the web app with an **email and password** (or single sign-on, if their account uses it), which starts a browser session. Software talks to the REST API with an **API key**, a secret token sent on every request. This page covers signing in; for the API in depth, see the [API reference for authentication](/api-reference/authentication).

## Sign in to the web app

Signing in is a two-step, email-first flow:

<Steps>
  <Step title="Enter your email">
    On the sign-in screen, type your email and click **Continue**. Terminus checks whether your email's domain uses single sign-on.
  </Step>

  <Step title="Enter your password, or continue with SSO">
    If your domain uses a password, the password field appears: type it and sign in. If your domain enforces SSO, Terminus sends you to your identity provider to sign in there instead.
  </Step>
</Steps>

A successful sign-in starts a secure browser session. If you belong to more than one account, you pick which one to work in after signing in; if you belong to exactly one, Terminus opens it for you.

<Note>
  Creating an account, confirming your email, resetting a forgotten password, and unlocking a locked account are all part of this flow. You must confirm your email before you can sign in. The first time you sign up, Terminus also creates a workspace named **Main** for you.
</Note>

### Single sign-on

If an account has SSO configured, members of its email domain sign in through their identity provider rather than with a password. Account owners and admins can still sign in with a password even when SSO is enforced, so they always have a way in. Setting up SSO is an account-level configuration.

### If you cannot sign in

<AccordionGroup>
  <Accordion title="It says my email or password is invalid, but I'm sure they're right">
    For security, a wrong password, an unknown email, and a temporarily locked account all show the same message. After several failed attempts an account locks for a short time. Wait a few minutes and try again, or use the unlock link Terminus emails you.
  </Accordion>

  <Accordion title="I never confirmed my email">
    You cannot sign in until your email is confirmed. Use the resend option on the check-your-email screen to get a fresh confirmation link.
  </Accordion>

  <Accordion title="It won't let me use a password">
    Your account's domain may enforce single sign-on. Sign in through your identity provider instead. If you are an owner or admin, password sign-in still works for you.
  </Accordion>
</AccordionGroup>

## Authenticate API requests

For anything programmatic (integrations, scripts, automation), use an **API key** instead of a session. A key is a secret bearer token that you send in the `Authorization` header on every request.

```bash theme={null}
curl https://hub.terminus.app/api/v1/records \
  -H "Authorization: Bearer thub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Keys are **account-scoped**, not tied to a person, so they keep working after the teammate who created one leaves. A key can do whatever its account can do through the public API; it cannot reach admin-only endpoints, and it can only ever read or write its own account's data.

<Warning>
  An API key is shown in full only once, at the moment you create it. Terminus stores only a secure hash of it and can never display it again. Copy it into a secrets manager right away. If you lose a key, delete it and create a new one.
</Warning>

### Create and manage keys

API keys are managed through the API itself. Create one by sending its name to the keys endpoint while authenticated:

```bash theme={null}
curl -X POST https://hub.terminus.app/api/v1/api_keys \
  -H "Content-Type: application/json" \
  -d '{"name": "CI pipeline"}'
```

The response includes the full key one time. Listing keys afterward returns each key's name and when it was last used, but never the secret itself. To revoke a key, delete it; the token stops working immediately. Only account owners and admins can create or delete keys.

For the full request and response shapes, error codes, and rate limits, see the [API reference for authentication](/api-reference/authentication) and the [API keys reference](/account/api-keys).

<Tip>
  Keep keys out of client-side code and version control. Load them from an environment variable or a secrets manager, and rotate them on a schedule (create the new key, switch your services over, then delete the old one).
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="API authentication reference" icon="key" href="/api-reference/authentication">
    Header format, error responses, and account scoping for API key auth.
  </Card>

  <Card title="API keys" icon="lock" href="/account/api-keys">
    Create, list, and revoke the keys for your account.
  </Card>

  <Card title="API overview" icon="code" href="/api-reference/overview">
    Base URL, response shapes, and which resources the public API covers.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Sign up and run the full Terminus Hub flow.
  </Card>
</CardGroup>