Set up your organisation

The steps in the Console that come before your code works — and the one whose absence makes the first call fail.

An organisation is the unit Amy keeps separate: its members, API keys, model provider keys, agents, tool servers, webhooks, memory, runs and usage all belong to one organisation and are never visible to another. Your API key identifies the organisation, so you never send an organisation id with a call.

1. Sign up and verify your email

Sign up with your name, email and a password. Amy sends a verification email, and the account cannot be used until you follow the link in it. Verifying creates your first organisation, named after you, with you as its Admin.

A new organisation starts on the free plan. The plan sets your monthly token allowance and how many API keys you can hold; see Limits and the pricing page for the current values. The allowance counts only Amy-provided model access: calls on your own provider key (step 4) are billed by your provider.

2. One organisation per product

If you are building more than one product on Amy, give each its own organisation. Everything below is per organisation, so each product gets its own keys, its own agents, its own memory and its own usage and bill, and an incident or a leaked key in one never reaches another.

In the Console, open Members and use New organization (the sidebar header also has an organisation switcher). You become the new organisation's Admin, and it starts on the free plan too.

3. Invite your team

On Members, the Invitations card sends an invitation by email with one of three roles. Invitations are single-use and expire after 48 hours, and the invitee must verify their email before joining.

Everything this guide asks you to do needs an Admin. Your API keys are not members and cannot do any of it: a key can call the /v1 API and nothing in the Console.

4. Add the model provider key

{
  "title": "No AI provider configured.",
  "status": 422,
  "detail": "API-key and scheduled runs use organization → platform keys; a member's personal key is never used. Add an Organization-scoped key and pick a default model in Console → AI Providers.",
  "code": "no_provider_credential"
}

The body also carries the usual ProblemDetails type, instance and traceId. Branch on code, never on the text.

Amy runs the agent on a model provider you choose, using your own key with that provider. In the Console open AI Providers, then:

1. Choose the Organization tab. (Runs started with an API key use the organisation's keys; a member's personal My keys are never used for them.)
2. On the LLM tab, pick a provider, paste its key and save it. Keys are stored encrypted and are never shown again.
3. Choose the default model for that tab. The key says which provider you can use; the default model says which model runs. A key alone does not choose the model, so always set one.

The provider list includes OpenAI, Anthropic, Google Gemini, xAI (Grok), Groq, DeepSeek and OpenRouter for chat. The other tabs — Embeddings, Vision, OCR, Web search, Text-to-Speech, Speech-to-Text and Image — bind the same way and switch on the matching tools for agents. Only the chat binding is needed for a run to start; without an Embeddings binding, memory still works but recalls by text search rather than by meaning.

A single run can also name its own model with the optional model field of the run request, and an Admin can give one agent its own model on that agent's page in the Console (see Agents). Either model still needs a key for its provider and a price on record, or the run is refused up front. Keep the default model set: it is what every agent without its own model uses.

Amy-provided model access. If your agreement includes Amy-provided model access, we enable it for your organisation and you can skip this step. The Organization tab shows whether that fallback is on for you.

5. Create an API key

Console → API keys → Create a key. Give it a name (up to 100 characters) and, if you want, an expiry between 1 and 3650 days. The key looks like amy_live_<keyId>.<secret> and is shown exactly once — Amy stores only a hash of the secret, so a lost key cannot be recovered; revoke it and create another.

• Per environment. Make one key for your production back end and a separate one for staging or development, so each can be revoked alone. The plan caps how many live keys the organisation may hold (the free plan allows two), and revoking a key frees its place.
• Rotation has no cutover. Create the new key, move your servers to it, then revoke the old one. Revoking takes effect on that key's very next request. Runs, conversations and files belong to your organisation's client, not to one key, so a rotated key still reads what its predecessor wrote.
• Files your keys send. Amy keeps them until you delete them. If your product keeps its own copy, turn Keep files sent by API keys off on the same page: each file is then deleted once every run that reads it has ended. To delete the files sent before, press Also delete the files already kept under the switch — it counts them, and deletes exactly that count once you confirm. See Files.
• The key stays on your server. Never ship it in a browser or mobile app. See Build your product on Amy.

See Authentication for how the header is used.

6. Prove it works

With a key and a provider in place, one call confirms the whole chain. If it returns a run with "status": "completed", the set-up is done.

# Keys are created in the Console (Console → API keys), by an organisation Admin.
# This is the call that proves the whole set-up works:
curl -X POST https://api.askamy.co.za/v1/agents/amy/runs/await \
  -H "X-Api-Key: $AMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Reply with the word ready.", "endUserRef": "setup-check" }'

7. Decide your inference privacy

Under AI Providers → Organization → Inference privacy an Admin can require verified zero data retention and/or no training on your data for every model call the organisation makes. A call that cannot meet the policy is refused before anything is sent to a provider. Your own systems can read the policy's current state with GET /v1/organisation/inference-privacy. Details, and what the guarantee does not cover, are in Data and privacy.

What happens next

• Define your own agent, if the default one is not what you want: Agents.
• Connect your systems as tools: Tools and MCP.
• Be told when work finishes: Webhooks.
• Read the whole pattern end to end: Build your product on Amy.