Authentication

Authentication is how you prove who you are so the API knows which requests to trust and how to rate-limit them. Start with the public guest curl path when you want to try one orchestrated run without an account. Pick an API key for server-side and CLI work, or a Clerk JWT for browser and mobile sessions. Once you've chosen a method, API Keys covers provisioning credentials and Rate Limits covers the ceilings each method carries.

Authentication

Every request carries one of three credentials, and the credential decides which account the run is recorded against.

Authentication Methods

API Key Authentication

API keys use the ivy_ prefix (not ivy_sk_). Three header formats are accepted:

# Preferred format
curl -H "Authorization: Bearer ivy_your_key_here" \
  https://www.ivybiosciences.com/api/v1/jobs

Creating API Keys

Only a signed-in Clerk session can create an API key; an API key cannot create another key. Create keys in the web app at Settings → API keys, or call the same route with a session token:

curl -X POST https://www.ivybiosciences.com/api/user/api-keys \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Pipeline", "scopes": ["read", "write"]}'

See API Keys for full management documentation.

Clerk JWT Authentication

For browser and mobile applications using Clerk:

import { useAuth } from "@clerk/nextjs"

const { getToken } = useAuth()

const response = await fetch("/api/v1/jobs", {
  headers: {
    "Authorization": `Bearer ${await getToken({ template: "ivy_api" })}`,
  },
})

Guest access

The supported public guest entry point is POST /api/v1/orchestrate. It needs no API key or guest header; send a natural-language prompt and let the orchestrator choose the allowlisted tools.

curl -N https://www.ivybiosciences.com/api/v1/orchestrate \
  -H "Content-Type: application/json" \
  -d '{"prompt":"find recent papers on EGFR L858R resistance","stream":true}'

Guest Restrictions

See the guest curl quickstart for the supported public flow.

Scopes

An API key carries up to three capabilities. A new key gets read and write unless you ask for others.

Scope Inheritance

Each capability includes the ones below it:

manage ⊃ write ⊃ read

Keys created before this vocabulary existed keep working: older domain scopes such as jobs:read or tools:all map onto these three.

Project Scoping

Jobs and projects can be scoped to an organization:

curl -X POST https://www.ivybiosciences.com/api/v1/jobs \
  -H "Authorization: Bearer ivy_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "esmfold",
    "tool_input_parameters": {"protein_sequence": "..."},
    "orgId": "org_abc123",
    "projectId": "proj_def456"
  }'

An API key can also be restricted to a list of projects when you create it in settings (allowedProjectIds). A restricted key reaches only jobs in those projects, on every job route, including status, outputs, downloads, manifests and artifact content. A job with no project, or in any other project, is refused even if your account can open it. The refusal is a 403 or 404 that does not say whether the job exists. A key with no project list reaches every job your account can.

A job's files are stored under the project it ran in. If a job was later moved to another project, a key restricted to the new project can read the job's status but not those files. Use an unrestricted key or a signed-in session for them.

Rate Limits

Limits are set per route and per client, not per authentication method. Signed-in callers (Clerk JWT or API key) get the same per-minute and per-second ceilings; a guest orchestrate call also draws on the daily guest quota in Guest curl.

A throttled request returns HTTP 429 with a Retry-After header. Rate Limits lists the ceilings, the response bodies, and how to back off.

Error Format

Most web API routes, including the Harness routes, return this envelope:

{
  "success": false,
  "code": "MACHINE_READABLE_CODE",
  "message": "Human-readable error message"
}

Errors forwarded from the compute backend keep its FastAPI shape, {"detail": "..."}.

Read next

• API Keys — create and manage API keys
• Guest curl — unauthenticated trial access through the public orchestrator
• Rate Limits — detailed rate limit documentation
• Error Codes — complete error reference