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

# Authentication

> hConnect exposes two auth surfaces: Workspace API uses Bearer tokens; App-scoped endpoints use Basic auth. This guide explains which credentials to use and when.

hConnect uses **two distinct authentication schemes** depending on which surface you are calling. Mixing them is the most common cause of `401` errors for new integrators.

## Auth schemes at a glance

| Surface           | Header value                                         | Credentials                                                        | Used for                                                           |
| ----------------- | ---------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |
| **Workspace API** | `Authorization: Bearer sk_workspace_...`             | Workspace API key (from Console → Developers → Workspace API Keys) | Managing Apps, Workflows, Providers, Activation, Production Tests  |
| **App API**       | `Authorization: Basic base64(clientId:clientSecret)` | App credentials (returned once by `POST /apps`)                    | `/verifications`, `/userinfo`, and other end-user-facing endpoints |

### Workspace API — Bearer auth

The Workspace API uses your **workspace key** — a long-lived API key tied to your workspace (not a specific App). Your workspace is your Hopae Connect account, created automatically when you sign up through the Console — see [What is a workspace?](/api-reference/workspace/introduction#what-is-a-workspace). Prefix the key with `Bearer`:

```bash theme={null}
curl -H "Authorization: Bearer sk_workspace_test_..." \
  "https://sandbox.api.hopae.com/connect/v1/apps"
```

Workspace keys are environment-specific. A `sk_workspace_test_...` key only works against the sandbox base URL (`https://sandbox.api.hopae.com`). Production keys begin with `sk_workspace_prod_...`.

### App API — Basic auth

App-scoped endpoints use **Basic auth** with the `clientId` and `clientSecret` of a specific App. These credentials are returned once when you call `POST /apps` (see [Create App](/api-reference/workspace/create-app)) and must be persisted by you — there is no retrieval endpoint.

```bash theme={null}
# Encode credentials
CREDENTIALS=$(echo -n "clientId:clientSecret" | base64)

curl -H "Authorization: Basic $CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"providerId": "frejaid"}' \
  "https://sandbox.api.hopae.com/connect/v1/verifications"
```

Or with cURL's built-in `--user` shorthand:

```bash theme={null}
curl --user "clientId:clientSecret" \
  -H "Content-Type: application/json" \
  -d '{"providerId": "frejaid"}' \
  "https://sandbox.api.hopae.com/connect/v1/verifications"
```

## Typical integration sequence

Most integrations follow this order:

1. **Create an App** — call `POST /apps` with your workspace Bearer token. The response contains `clientId` and `clientSecret`. **Persist both values immediately.**
2. **Activate providers** — use workspace Bearer token to call activation endpoints.
3. **Run verifications** — use the App's `clientId:clientSecret` as Basic auth on `/verifications` and related endpoints.

```bash theme={null}
# Step 1 — Workspace Bearer: create an App
curl -X POST \
  -H "Authorization: Bearer sk_workspace_test_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My App"}' \
  "https://sandbox.api.hopae.com/connect/v1/apps"
# → save clientId and clientSecret from the response

# Step 2 — Workspace Bearer: activate a provider
curl -X PATCH \
  -H "Authorization: Bearer sk_workspace_test_..." \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}' \
  "https://sandbox.api.hopae.com/connect/v1/apps/{clientId}/providers/frejaid/activation"

# Step 3 — App Basic: run a verification
curl --user "{clientId}:{clientSecret}" \
  -H "Content-Type: application/json" \
  -d '{"providerId": "frejaid"}' \
  "https://sandbox.api.hopae.com/connect/v1/verifications"
```

## Troubleshooting

<Warning>
  **"401 Invalid authorization scheme. Use Basic authentication"** on a verification call means you are sending the Workspace Bearer token where Basic auth is required. Switch to `Authorization: Basic base64(clientId:clientSecret)` using the App credentials from `POST /apps`.
</Warning>

<Warning>
  **"401 Unauthorized"** on a Workspace API call (e.g., `GET /apps`) when you send Basic auth means the reverse — those endpoints require `Authorization: Bearer sk_workspace_...`.
</Warning>

<Note>
  The App `clientSecret` is returned **once** at creation time. If you lost it, you must create a new App. See [Create App](/api-reference/workspace/create-app) for details.
</Note>

## Related pages

* [Create App](/api-reference/workspace/create-app) — how to obtain `clientId` and `clientSecret`
* [Create Verification](/api-reference/verifications/create-verification) — using Basic auth for verifications
* [Workspace Introduction](/api-reference/workspace/introduction) — workspace key setup