Skip to main content
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

SurfaceHeader valueCredentialsUsed for
Workspace APIAuthorization: Bearer sk_workspace_...Workspace API key (from Console → Developers → Workspace API Keys)Managing Apps, Workflows, Providers, Activation, Production Tests
App APIAuthorization: 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?. Prefix the key with Bearer: 
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) and must be persisted by you — there is no retrieval endpoint. 
# 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: 
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.
# 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

“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.
“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_....
The App clientSecret is returned once at creation time. If you lost it, you must create a new App. See Create App for details.