Skip to Content

API Key Authentication

The hosted Agent SDK uses an API key to authenticate requests to the isA Model Service. In the isa_mate integration, the SDK calls POST /api/v1/invoke against the configured model gateway; it does not use the Console’s OpenAI-compatible /v1/chat/completions snippet. A completely offline local runtime does not need a Console account; the steps on this page apply to the hosted cloud runtime and to edge when it uses cloud services.

1. Create a key in isA Console

  1. Open the isA Console and sign in.
  2. Select or create an organization.
  3. In Developer, create or select a project before creating a project-scoped key. Organization-wide keys can be used when a project is not required.
  4. Open Developer → API Keys. The direct route is /dashboard/developer/api-keys within the Console.
  5. Select Create new key.
  6. Give the key a recognizable name. For a production integration, choose a project scope, use a service-account owner, and set the smallest required scopes, expiry, IP allowlist, rate limit, and spend limit.
  7. Create the key and copy it immediately. The full secret is shown only once; the inventory later shows only a preview.

Do not commit the key to source control or put it in a browser bundle. If it is exposed, revoke it from the same API Keys page and create a replacement.

2. Configure the SDK

The SDK reads ISA_API_KEY from the environment. ISA_MODEL_API_KEY takes precedence when you need a separate key specifically for Model Service calls.

export ISA_API_KEY="YOUR_API_KEY"

For a local project, you may put the value in an ignored .env file, but make sure your process loads it. The SDK reads process environment variables; a .env file is not automatically visible to every Python process:

ISA_API_KEY=YOUR_API_KEY

For a shell command, load that file explicitly:

set -a; source .env; set +a

The Console may display keys with a prefix such as sk-isa-. Copy the complete value exactly as shown; do not add quotes, the word Bearer, or a trailing comment to the value.

3. Make a first call

import asyncio
from isa_agent_sdk import ask
 
 
async def main() -> None:
    answer = await ask("What is the capital of France?")
    print(answer)
 
 
asyncio.run(main())

For an explicit remote Agent client, pass the key directly instead of using ISA_API_KEY:

from isa_agent_sdk import ISAAgent
 
client = ISAAgent(
    api_key="YOUR_API_KEY",
    base_url="https://your-agent-service.example.com",
)

The client sends the key as Authorization: Bearer <key>.

Verify the key before debugging your agent

Use the same base URL that isa_mate passes as ISA_API_URL/services.model_url. The hosted edge profile currently uses https://api.isagent.io:

export ISA_API_URL="https://api.isagent.io"
curl -i "$ISA_API_URL/api/v1/models" \
  -H "Authorization: Bearer $ISA_API_KEY"

To exercise the same request path used by isa_mate:

curl -i -X POST "$ISA_API_URL/api/v1/invoke" \
  -H "Authorization: Bearer $ISA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","task":"chat","service_type":"text","input_data":[{"role":"user","content":"Reply with exactly OK."}]}'

The Console may show a different OpenAI-compatible snippet. Treat it as a separate surface until its host and path are verified for your deployment.

The public Console and API domains may differ by deployment. Do not derive the API host by replacing the Console hostname; use services.model_url or ISA_API_URL from the deployment configuration.

An HTTP 401 normally means the key is missing, mistyped, expired, or revoked. An HTTP 403 normally means the key is valid but its scopes, organization, or project do not allow the requested operation.

Rotate or revoke a key

Create the replacement first, update the deployment secret, verify a request, then revoke the old key in Developer → API Keys. Treat a revoked key as permanent; do not reuse it.

Home