Credentials API

Optionally bring your own provider credentials for tenant defaults or agent-specific overrides.

Provider credentials let Hyperstruck call a model provider through your account instead of the platform default. They are optional for the first run because Hyperstruck can use a platform-owned fallback credential and intelligently select the best-suited model.

Access control

Read operations require credentials:read and org developer membership (or an API key). Write operations require credentials:write and org admin membership (or an API key). See Access control (FGA and RBAC).

Start without credentials

Most teams can create an agent and dispatch a goal without uploading provider credentials. Use this API when you want to control the provider account, billing path, endpoint, or agent-specific model setup.

Bring your own key when needed

A tenant_default applies to all agents using that provider. An agent_override wins for one agent. If neither exists, Hyperstruck uses the platform default when it is enabled.

What provider credentials do

They let Hyperstruck use your provider key at runtime.
They are selected by provider, not by arbitrary label.
They can override the platform default for a tenant or for one agent.
They can store provider endpoint metadata such as metadata.base_url.

Upload a tenant-default credential

Prop

Type

Do not include agent_id when binding_type is tenant_default.

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://api.hyperstruck.com/credentials/providers" \
  -d '{
    "provider": "anthropic",
    "display_name": "Default Anthropic Key",
    "binding_type": "tenant_default",
    "secret": "<ANTHROPIC_API_KEY>"
  }'

Required scope: credentials:write

Upload an agent-override credential

agent_id becomes required when binding_type is agent_override.

Prop

Type

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://api.hyperstruck.com/credentials/providers" \
  -d '{
    "provider": "anthropic",
    "display_name": "Agent-Specific Anthropic Key",
    "binding_type": "agent_override",
    "agent_id": "<AGENT_ID>",
    "secret": "<ANTHROPIC_API_KEY>"
  }'

Required scope: credentials:write

Common next knobs

metadata.base_url is optional.

If metadata.base_url is omitted:

anthropic stores https://api.anthropic.com
groq stores https://api.groq.com
ollama stores https://ollama.com/api
openai stores https://api.openai.com/v1
google, mistral, and xai store their provider defaults

Legacy metadata.endpoint is accepted, but public docs should prefer metadata.base_url.

Runtime credential resolution

When running an agent, Hyperstruck resolves credentials in this order:

It checks the agent's model_provider.
A matching active agent_override credential for that agent wins first.
If no matching agent_override exists, Hyperstruck falls back to the tenant's matching active tenant_default credential.
If neither exists, Hyperstruck uses the platform default credential and intelligently selects the best-suited model.

Agent responses can include an llm_credential summary. Customer credentials include a credential_id; platform fallback summaries use credential_id=null, source="platform_default", and platform_override=true.

How this affects runs and manual learning

Agent execution uses your matching customer credential when one exists.
Without a matching customer credential, agent execution can use the platform default and automatic model selection.
Manual learning storage does not require you to upload an LLM provider credential first.
Teams only need tenant_default or agent_override credentials when they want to bring their own provider account.

Other operations

You can list, retrieve, update, and delete provider credentials:

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/credentials/providers?provider=groq"

Required scope for list and retrieve: credentials:read

curl -X PATCH \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://api.hyperstruck.com/credentials/providers/<CREDENTIAL_ID>" \
  -d '{
    "display_name": "Updated Groq Key",
    "metadata": {
      "base_url": "https://api.groq.com"
    }
  }'

Required scope for update and delete: credentials:write

List filters include provider, binding_type, agent_id, and include_inactive. include_inactive defaults to false.

Access control (FGA and RBAC) for role and scope requirements
Quickstart for the fastest first-success flow
Agents API for creating agents and dispatching runs
Learnings API for manual learning storage

On this page