Authentication

Every FYAI API request needs a credential. For code you write, that credential is an API key. This page covers how to create one, how to send it, what it can do and how it's scoped.

Credential types

Credential	Header	Who uses it	Lifetime
API key (starts with fyai_)	X-API-Key: fyai_...	Your scripts, services, CI jobs and the platform MCP server	1 day to 1 year, chosen when you create it
Access token (a JWT)	Authorization: Bearer ...	Returned when you exchange an API key or service account credentials; also what the web app uses for your browser session	Minutes — read expires_in
Service account client ID and secret	Exchanged for an access token	Machine identities provisioned for you	Until deleted

Use an API key unless you have a specific reason not to. All four public API hosts (agent, catalog, integration and auth) accept the X-API-Key header directly.

Create an API key

1. Open Settings. Under My account, select API Keys.

2. Select Create Key.

3. Fill in the Create API Key dialog:

   Field	What to enter
   Key Name	Something that tells you where the key is used, for example CI/CD Pipeline. Up to 100 characters.
   Expiry	7 days, 30 days (default), 60 days, 90 days, 180 days or 1 year.
   Access	What the key may do in the project. See Access levels. The list only shows levels you're allowed to grant.

4. Select Create.

5. The API Key Created dialog shows the key once. Copy it and store it somewhere safe, such as your CI system's secret store. Select Done.

warning

FYAI stores only a hash of the key. If you lose it, revoke it and create a new one.

Which project a key belongs to

A key is bound to the organisation and project you're working in when you create it. Everything the key does — listing agents, running workflows, creating knowledge bases — happens in that project. To automate a different project, switch to that project in the web app first, then create a key there.

You can't move a key to another project, and you don't pass a project or organisation ID in API requests: the platform works it out from the credential.

Access levels

Each key carries one access level, which maps to a project role:

Access	Project role	What the key can do
Run	project:runner	Launch only the agents and workflows it has been granted. Can't read or change configuration.
Read	project:viewer	List and read resources. Can't create, change or run anything.
Write (default)	project:editor	Create, change and run resources in the project.
Admin	project:admin	Full control of the project, including its members and settings.

You can't create a key with more access than you have yourself in that project. If you're an editor, the Admin option doesn't appear, and the API refuses the request with 403.

Some operations need more than the key's project role. For example, deleting an agent needs Admin. Organisation owners and admins have full rights in every project of their organisation, but a key they create still carries only the Access level chosen for it. Roles are described in Members and roles.

note

A Run key starts with no launch rights. Launch rights for a key are granted by a project admin per agent or workflow, and the web app doesn't yet have a screen for granting them to a key. For most automation, use Write.

Manage and revoke keys

The Your API Keys list on the API Keys page shows the keys you created in the current organisation. Each row shows:

• the key name
• a status chip: Active, Expired or Revoked
• its access level (Run, Read, Write or Admin)
• a short identifier, the created and expiry dates, and when it was last used

To revoke a key, select the trash icon on its row, then Revoke. Revoking takes effect immediately: any application using the key loses access on its next request. An expired key can't be renewed — create a new one.

A program holding a key can also revoke its own key, without knowing its ID:

curl -X DELETE -H "X-API-Key: $FYAI_API_KEY" https://auth.fyai.co.nz/api-keys/current

Use an API key

Send it on every request

The simplest approach is to send the key in the X-API-Key header on every request, to any host:

curl -H "X-API-Key: $FYAI_API_KEY" https://agent.fyai.co.nz/agents
curl -H "X-API-Key: $FYAI_API_KEY" https://catalog.fyai.co.nz/workflows
curl -H "X-API-Key: $FYAI_API_KEY" https://integration.fyai.co.nz/integrations

Each service checks the key on each request, so revoking or expiring a key stops it working straight away.

Sending the key directly also matters for long-running work. When you start a workflow with an API key, the platform can keep renewing the run's credential from your key, so a run that lasts hours keeps working. A workflow started with a short-lived bearer token can't renew its credential and may fail partway through.

Or exchange it for an access token

If you'd rather send a bearer token, exchange the key first. This is what the Usage panel on the API Keys page shows:

curl -X POST -H "X-API-Key: $FYAI_API_KEY" https://auth.fyai.co.nz/api-keys/validate

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "expires_in": 210
}

Then call the APIs with it:

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://agent.fyai.co.nz/agents

The token is short-lived. Re-exchange the key before expires_in seconds have passed. If a request includes both an Authorization header and an X-API-Key header, the bearer token is used.

Service accounts

A service account is a machine identity with a client ID (starting sa-) and a client secret, bound to one organisation and project with a project role. Every API key is backed by a service account behind the scenes.

The Service Accounts page under Settings → Project is shown only to FYAI platform administrators. For your own automation, use an API key.

If you've been given a service account's client ID and secret, exchange them for a five-minute access token:

curl -X POST https://auth.fyai.co.nz/service-accounts/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "client_credentials", "client_id": "sa-...", "client_secret": "..."}'

{ "access_token": "eyJhbGciOi...", "token_type": "bearer", "expires_in": 300 }

This endpoint allows 30 requests a minute from one IP address. Cache the token and reuse it until it's close to expiry.

Agent identities

Each agent can have its own platform identity, so actions it takes through platform tools are attributed to the agent rather than to the person chatting with it. You manage this on the agent's Identity tab, or with GET /agents/{agent_id}/identity and PATCH /agents/{agent_id}/identity/active on the agent API. See Agents.

WebSocket authentication

Send your credential in a header when you open the WebSocket, the same way you do for a REST call. Either header works:

• X-API-Key: fyai_...
• Authorization: Bearer <access token>

wscat -c wss://agent.fyai.co.nz/ws/events -H "X-API-Key: $FYAI_API_KEY"

import websockets

async with websockets.connect(
    "wss://agent.fyai.co.nz/ws/events",
    additional_headers={"X-API-Key": api_key},
) as ws:
    ...

additional_headers is the name in websockets 14 and later; earlier releases call it extra_headers. See the events stream in Platform API.

warning

Credentials in the query string, ?api_key= and ?token=, are deprecated. They still work today, but a URL is written to access logs and proxy logs and can be copied into browser history and Referer headers, so a credential in it leaks. Move existing code to a header now, and don't use the query string in new code. Support for it may be removed in a future release.

Browsers can't set headers on a WebSocket. The web app doesn't need to, because it authenticates with your signed-in session. Don't embed an API key in browser code to get around this: call the API from a server you control, and send the key in a header from there.

Authentication errors

Status	Message	What it means
401	Not authenticated – token missing	The request had no credential.
401	API key required	A call to /api-keys/validate had no X-API-Key header.
401	Invalid API key / API key expired / Malformed API key	Returned by /api-keys/validate: the key was revoked, has expired, or was mistyped. Create a new key.
401	Could not validate credentials	Returned by the agent, catalog and integration services when a key is rejected (revoked, expired or mistyped) or a bearer token has expired.
403	Requires project:editor or higher (you have project:viewer)	The credential's access level is too low for this operation.
403	No permission to launch this agent / workflow	The credential has Run access without a grant for this resource.
503	Authentication service unavailable, please retry / Identity provider could not issue a token; retry shortly	A temporary problem checking the credential. Retry with backoff; the key is fine.

tip

Keep keys out of source control and logs. Store them in your CI system's secret store or an environment variable, give each integration its own key so you can revoke one without breaking the others, and choose the shortest expiry and lowest access level that works.