Before you start
An AI agent such as Claude Code or ChatGPT Codex can query and operate your Odoo the way any other user would: it reads, filters, creates and configures records with the permissions of the user whose key it uses. This guide explains how to make that connection without handing the key to the agent and without putting your operation at risk. It is the same connection we use in our Odoo implementations with AI.
You need:
- An Odoo with the external API: Custom plan, Odoo.sh or on-premise. The Standard plan does not include it; further down we explain what to do in that case.
- The Claude Code or ChatGPT Codex desktop app, working on your computer. In the cloud chat the agent cannot run commands on your machine.
- A Secrevo account to store the key.
- An Odoo test database, separate from production, for risky changes.
Step 1: set up a test database for risky changes
Before asking an agent for a risky change in production, try it on a copy. On Odoo.sh that is the staging branch, which holds a copy of the production data and where Odoo holds outgoing emails and disables scheduled actions. If your Odoo runs on your own server, use a copy of the database. Whatever the agent does there is reviewed before it is repeated in production. For everyday, low-risk tasks, the agent can also operate directly in production, with just the permissions it needs and with review of what it does.
Step 2: choose the user and create its API key
The agent has exactly the permissions of the user who owns the key: if the user is an administrator, so is the agent. For an implementation, use a user that only has the access the task needs. The Odoo documentation recommends a personal account for interactive use and a dedicated user, with minimum permissions, for automated or unattended use. Keep in mind that in Odoo Enterprise each additional internal user requires a license.
To create the key, logged in as that user:
- Open your profile, top right, and go to My Preferences.
- On the Security tab, under API Keys, click Add API Key and confirm your password.
- Give it a description that says what it is for, for example «Ana's Claude Code, test database».
- Choose a short Duration. The Odoo documentation recommends one day for interactive use and does not allow keys longer than three months.
- Copy the key: Odoo shows it only once. Do not paste it into the agent's chat; go straight to step 3.
Create one key per agent or service. If you change computer or agent, you delete that key and create another, without affecting the rest.
Step 3: store the key in Secrevo
Everything that enters the agent's context, the chat, the files it reads or your emails, should be treated as exposed. That is why the key is not given to the agent: it is stored in Secrevo and the agent uses it without seeing it.
- Create your workspace at app.secrevo.com. Secrevo has a free plan.
- Under Secrets, create a secret, for example
ODOO_PRUEBAS, with three fields:url(the address you use to open Odoo, with https),database(the database name, shown in developer mode) andapi_key(the key from step 2). Fields are added with the Add field button. - Write a good description: what the secret is for, which user owns the key and how to regenerate it. The agent can read the description, so do not put secret values in it.
- Install the Secrevo command line on your computer. On Windows (PowerShell):
irm https://github.com/getsecrevo/cli/releases/latest/download/install.ps1 | iexOn macOS or Linux:
curl -fsSL https://github.com/getsecrevo/cli/releases/latest/download/install.sh | bashThen, in app.secrevo.com/agents create an agent, generate an enrollment code (single use, valid for 15 minutes) and redeem it on the computer. The code in the example is the one from the Secrevo documentation; use your own:
secrevo version
secrevo enroll K3M9-X2PA
secrevo auth whoamiCheck that the secret exists. Secrevo only shows the field names, never the values:
secrevo secret get ODOO_PRUEBAS
{
"name": "ODOO_PRUEBAS",
"fields": ["api_key", "database", "url"]
}Step 4: the first query to the /json/2 endpoint
In Odoo 19, the external API is JSON-2: every call is a POST to /json/2/<model>/<method>, with the key in the Authorization: bearer header and the named parameters in a JSON object. The old /xmlrpc and /jsonrpc routes are scheduled for removal in Odoo 22, so it is worth starting with JSON-2 now.
This is what a request looks like:
POST /json/2/res.partner/search_count HTTP/1.1
Host: your-test-db.odoo.com
Authorization: bearer <API key>
X-Odoo-Database: your-test-db
Content-Type: application/json; charset=utf-8
{"domain": [["is_company", "=", true]]}Points worth knowing, according to the Odoo 19 documentation:
X-Odoo-Databaseis needed when one server hosts several databases; otherwise it can be omitted.- All arguments are named:
ids,context,domain,fields. There are no positional arguments. - Each call is its own transaction: if it fails, nothing from that call is saved.
- Errors come with an HTTP status code and a JSON with
message; an invalid key returns 401. - To find out which user you are connected as, call
res.users/context_getwithout ids.
This example script asks which user it is connected as and reads five companies. It contains no key: it reads them from environment variables.
import os
import requests
url = os.environ["ODOO_URL"].rstrip("/")
headers = {
"Authorization": "bearer " + os.environ["ODOO_API_KEY"],
"X-Odoo-Database": os.environ["ODOO_DB"],
"Content-Type": "application/json; charset=utf-8",
"User-Agent": "odoo-agent-test",
}
r = requests.post(url + "/json/2/res.users/context_get", headers=headers, json={})
r.raise_for_status()
print(r.json())
r = requests.post(url + "/json/2/res.partner/search_read", headers=headers, json={
"domain": [["is_company", "=", True]],
"fields": ["name", "vat"],
"limit": 5,
})
r.raise_for_status()
print(r.json())And this is how it runs with Secrevo, which injects each field of the secret as an environment variable for that process only, without writing it to disk or displaying it:
secrevo run \
--secret-field ODOO_PRUEBAS.url=ODOO_URL \
--secret-field ODOO_PRUEBAS.database=ODOO_DB \
--secret-field ODOO_PRUEBAS.api_key=ODOO_API_KEY \
-- python odoo_test.pyIn practice you do not have to write the script: you ask the agent for it. For example: «Connect to my Odoo test database with the ODOO_PRUEBAS secret from Secrevo, using secrevo run and the /json/2 endpoint. Never print or display the secret's values. First tell me which user you are connected as and how many contacts there are.»
Good practices
- Start with read-only queries. When you move on to creating or changing records, ask the agent to explain what it will do first and approve it. Once you are comfortable, use the same connection with another secret (for example ODOO_PRODUCCION) to operate in production, with the same care.
- Check on the Odoo screen what the agent created or changed. The record's history shows which user did it.
- One key per agent, with a description and a short expiry. To rotate it, create the new one, update the secret in Secrevo and then delete the old one.
- Never keep keys in the chat, in emails, in notes or in files on your computer, because the agent can read them.
- Review your users' permissions before each person connects their own agent: each agent can do the same as its user.
- Ask precisely. «Sales» can mean orders, invoices or opportunities; the clearer you are, the fewer detours the agent takes.
If your plan has no API
On Odoo Online, the external API is only available on the Custom plan; not on One App Free or Standard. Without the API the agent cannot connect to your Odoo, but it is still useful:
- It prepares the import files (Excel or CSV) with the columns Odoo requires, from your data, and checks for duplicates and incomplete data.
- It guides you step by step to import them from the Odoo screen and to do the configuration by hand.
- If you later move to the Custom plan or Odoo.sh, the connection in this guide works without changing anything else.
Want to implement Odoo this way?
We use this connection from the first session of every implementation: your team defines with our consultant, its agent executes, in production too when it applies, and your team reviews. Learn about the method in Odoo implementation with AI.