Skip to Content

Odoo JSON-2 API: your first request with an API key (1/4)

Read your contacts from a script in ten minutes, with no password in the code.
November 19, 2026 by
ANOR, Cyrille de LAMBERT

In brief The Odoo JSON-2 API lets you query your data from an external script using an API key, with no password stored in the code. A single POST request to /json/2/res.partner/search_read is enough to retrieve a list of contacts in JSON format within minutes.

The result before the code

Imagine a script that fetches your Odoo contacts and displays them in your in-house tool, without storing a single password. That is exactly what the Odoo JSON-2 API makes possible. By the end of this tutorial you will have a JSON response containing contact names, from any HTTP client.

This article is the first in a four-part series. Episode 2 will cover migrating an existing XML-RPC script to JSON-2.

Warning: on Odoo Online, access to the external API depends on the type of plan subscribed (custom plan). Check your contract before you start, in line with the official Odoo documentation.

Step 1: create the API key

Log in to Odoo with the account that will make the calls. Open that user's Preferences, then the Account Security tab. Click New API Key, enter a meaningful description and choose a short duration for interactive use.

Copy the key immediately: it is only shown once. Security tip: use an account dedicated to the script, with only the rights it needs. The key inherits all the rights of its user. Store it in an environment variable or a secrets vault, never hard-coded in the source. Revoke it as soon as any doubt arises.

Step 2: prepare the HTTP call

The Odoo JSON-2 API expects a POST request to a URL of the form /json/2/model/method. To read contacts, the target URL is /json/2/res.partner/search_read.

Add these headers to your request:

  • Authorization: bearer followed by your key
  • Content-Type: application/json
  • X-Odoo-Database: database name (required if the server hosts several databases)
  • User-Agent: identify your script (recommended)

Step 3: write the JSON body

The request body is a JSON object. The essential keys for search_read are:

  • domain: search filter; an empty list returns all records
  • fields: list of fields to return, for example name and email
  • context: optional, useful for forcing the language with the value en_US

For methods that act on specific records, add the ids key containing the list of relevant identifiers.

Mini exercise: write a call that reads three contacts by adding the limit key with the value 3 in the body, then modify it to include the email field in the fields list. Check that the response contains the addresses.

Step 4: read the response

A successful call returns HTTP code 200 and a list of JSON objects. Each object represents a record. Example response:

Record 1: id 1, name "Dupont SA", email "[email protected]".
Record 2: id 2, name "Martin SARL", email "[email protected]".

Iterate over this list in your script like any JSON array. Missing or empty fields are returned with the value false.

To explore the models and methods available on your instance, visit the /doc page of your Odoo database: it lists all resources accessible via the API. Need help setting up your environment? The team is available on the Support page.

Step 5: decode common errors

When something goes wrong, the API returns an HTTP code and an explicit JSON body:

  • 401: invalid or missing key, exception name "Invalid apikey". Check the value and the bearer prefix.
  • 403: the user does not have rights on the requested model.
  • 400: malformed JSON body or unknown field. The exception message and its arguments are included in the response.

Always read the message field of the error body: it pinpoints the cause of the problem. If your integrations are growing and you want to structure your approach, a free audit can help you identify areas for improvement.

Next step: migrate your XML-RPC script

You now have a solid grasp of the Odoo JSON-2 API basics. Episode 2 of this series will show you how to rewrite an existing XML-RPC script to take advantage of this new protocol. To go further right now, explore the full capabilities of Odoo or take a look at our Odoo consulting offer.

Would you like an expert eye on your integration project? Request a free audit: we analyse your context and propose a tailored roadmap.

Frequently asked questions

Does the API key replace the username and password?

Yes. The API key is used alone in the Authorization header, with no username or password. It carries the rights of the user it belongs to.

How do I find the user ID associated with my key?

Call the context_get method on the res.users model without passing an explicit identifier. The response includes the uid of the user authenticated by the key.

What is the exact format of an error response?

The JSON body contains at minimum the fields name (exception name), message (human-readable description) and args (technical arguments). The HTTP code indicates the error category: 401 for an invalid key, 403 for a rights issue.

Can the JSON-2 API be used on all Odoo instances?

On Odoo Online, access to the external API is reserved for custom-type plans, according to the official documentation. On a self-hosted instance, the API is available without any plan restriction.

How can I reduce the risks associated with the API key?

Store the key in an environment variable or a secrets vault, never in the source code. Use a dedicated user with limited rights and revoke the key as soon as any doubt arises from the Account Security tab.

in Blog
ANOR, Cyrille de LAMBERT November 19, 2026
Share this post
Tags
Our blogs

A question about your project? Talk to a consultant.

Book 30 minutes