Authentication

Every Hull Gateway inference request needs a Hull API key, including requests for free models. Pass it as a Bearer token:

Authorization: Bearer <your_api_key>

Get your API keyCopy Anchor Link

1. Sign in at app.withhull.com with your personal account.
2. Open your Profile.
3. In the Integrations card, find API Key and copy it.

Treat the key like a password. If it leaks, choose Reset API Token in the same card. Resetting invalidates all your existing tokens, so you'll need to sign in again in the CLI, VS Code, JetBrains and other clients.

Hull Desktop, the IDE extensions and the Hull CLI sign you in through the browser and manage their own credentials, so you only need an API key when calling Hull Gateway from your own code.

Use your API keyCopy Anchor Link

import { createOpenAI } from "@ai-sdk/openai"

const hull = createOpenAI({
  baseURL: "https://api.withhull.com/api/gateway",
  apiKey: process.env.HULL_API_KEY,
})

A missing or invalid key returns HTTP 401.

OrganizationsCopy Anchor Link

To make a request as a member of an organization, add the organization ID header:

X-HullCode-OrganizationId: <your_org_id>

The request then uses the organization's usage pool and follows its policies: per-member spending limits on Teams and Enterprise, and model and provider policies on Enterprise. See Usage and billing.

Bring your own keyCopy Anchor Link

You can store provider keys in your Hull account so Hull Gateway sends matching requests with your key, and the provider bills you. Add keys on the Bring Your Own Key (BYOK) page at app.withhull.com/byok, or on your organization's BYOK page if you're an owner. For organizations, Enterprise BYOK is offered through an Enterprise agreement.

How it works:

• Keys are encrypted at rest and never shown again after you save them.
• When a request is for a model from a provider you have an enabled key for, Hull Gateway uses your key.
• BYOK usage is recorded but doesn't count against your Hull allowance.
• If your key fails, the request fails. It doesn't fall back to Hull's keys.

See Bring your own key for supported providers and credential formats.

Request headersCopy Anchor Link