API keys and agents

User

An API key lets an agent or a script act as you against the AiQu API - listing queues, booking jobs, reading what a run produced - without signing in through the web interface.

A key is not a token

In AiQu a token is a unit of billing credit, which is what the Tokens page is about. An API key is a credential. They are unrelated, and neither one can be spent as the other.

Creating a key

Open the account menu at the bottom of the navigation and choose API keys (it is also under Account settings). Choose New key, give it a name and an expiry.

The name is how you tell your keys apart later, so name it after the machine or the agent that will hold it - laptop agent, nightly retraining - rather than after yourself.

The secret is shown once. AiQu stores only a hash of it and cannot show it again. If you lose it, revoke the key and create a new one.

A key inherits the full authority of the user who created it. It can do anything you can do, including booking jobs that spend credits.

Connecting an agent

AiQu runs a hosted MCP server at mcp.<your-aiqu-host>. Nothing is installed locally: the agent connects over HTTPS and gets a set of AiQu tools.

Through the browser

Most agents need only the server URL. Open the account menu, choose Connect an agent (also under Account settings) and pick your agent: Claude Code, Claude Desktop, Codex CLI, opencode, Cursor, VS Code, or Something else. The page shows the URL for your installation and the config for that agent, with no key in it. For Claude Code:

claude mcp add --transport http aiqu https://mcp.aiqu.ai/mcp

The first time the agent connects it opens AiQu in your browser. Sign in if you are not already, and an approval page names the agent and the address the approval is sent to. Check that address: an agent can call itself anything, but where the approval goes is what gives an impostor away.

Approve creates an API key for the agent, named MCP: <agent name>, and hands it over without you ever seeing it. It has your full authority and no expiry, like any other key. It shows up in your list of API keys, and revoking it there disconnects the agent.

When the page shows a key instead

If browser login is turned off on your installation, or the MCP server cannot be reached, Connect an agent says so and points you to an API key instead.

With an API key

CI jobs, scripts and agents on a remote machine cannot complete a browser login. Give them a key: after you create one, the API keys page shows the config for each agent with the key already in it:

claude mcp add --transport http aiqu https://mcp.aiqu.ai/mcp \
  --header "Authorization: Bearer aiqu_sk_..."

The same URL works in any client that speaks MCP over Streamable HTTP.

What the agent can then do

whoami	Who the key belongs to, and what they may spend
list_queues, list_nodes, list_images	What can be booked, and on what
list_projects	Your projects, their balance, and which one is your default
check_availability	When a job of a given shape could start, and the cost
create_job, clone_job, extend_job, cancel_job	Book a job of one or more services, rerun an earlier one, extend and cancel
list_jobs, get_job, get_job_logs	Follow what is running
list_buckets, browse_storage, read_file	Read what a run produced, without booking anything
list_port_proxies, create_port_proxy, delete_port_proxy	Reach a TensorBoard or code-server inside a job
run_in_job	Run a shell command in a running job, like the terminal in the web UI

A job holds one or more services. Booking, extending, cancelling and cost apply to the whole job, which the tools address by job_id. Logs, the shell and port proxies belong to one service, addressed by service_id. list_jobs shows both.

create_job and check_availability take an optional project_id that charges the job to a project, the same as the project picker in the submission form. On a queue that requires a project, a booking without one goes on your default project, and is refused if you have none, so ask the agent to call list_projects first.

Booking, cancelling, exposing a port and running a command in a job are marked as destructive, so a well-behaved agent asks before it does any of them. Ask your agent to check availability and tell you the cost before it books.

Reading results is free

browse_storage and read_file answer “what did that training run produce” without booking a job. That is usually the question, and it costs nothing.

Using a key directly

Any AiQu API endpoint accepts a key in place of the Session and Token header pair:

curl -s https://rest.aiqu.ai/job \
  -H "Authorization: Bearer aiqu_sk_..."

Send the key instead of Session and Token, not alongside them - if a Session header is present it is used and the key is ignored.

Expiry and revocation

A key stops working when its expiry passes. The list marks a key expiring within seven days, so rotate it before something breaks at three in the morning. Keys created with Never keep working until revoked.

Revoking takes effect immediately, including for an agent connected right now. Revoke a key as soon as you suspect it has leaked - into a chat, a paste bin, a commit - and create a new one. There is no cost to having done it unnecessarily.

Keeping a key safe

• Treat it like a password. It acts as you.
• One key per machine or agent, so that revoking one does not disconnect everything you own.
• Never commit one. Keys start with aiqu_sk_, which secret scanners can be told to look for.
• Prefer an expiry over Never for anything that is not long-lived infrastructure.