OAuthLib

A generic, spec-compliant, thorough implementation of the OAuth request-signing logic for Python. Without OAuthLib installed the OAuth1 and OAuth2 authentication methods are automatically disabled and only Basic authentication is available. To install OAuthLib please follow the instructions or install the library via pip.

pip install oauthlib

Server-wide Loading

In case the module should be active in every database just change the auto install flag to True. To activate the routes even if no database is selected the module should be loaded right at the server start. This can be done by editing the configuration file or passing a load parameter to the start script.

Parameter: --load=web,muk_rest

Multi-database Environment

To access the API in a multi-database environment without a db filter, the name of the database must be provided with each request via a query parameter or a custom header.

Query parameter: ?db=<database_name>

The header name and query parameter name are configurable via the rest_db_header and rest_db_param configuration parameters (defaults: DATABASE and db).

OAuth Configuration

To configure this module, you need to:

1. Go to Settings -> API -> Overview. Here you can see an overview of all your API configurations (OAuth1 and OAuth2 clients).
2. Click on Create or go to either Settings -> API -> Configuration -> OAuth1 or Settings -> API -> Configuration -> OAuth2 to create a new API configuration.

Settings

Additional settings are available under Settings -> API -> Configuration -> Settings (General Settings page, API section):

Docs Security

Restrict access to the interactive API documentation (/api/docs) to members of a specific security group. When no group is selected, the documentation is accessible to any authenticated user.

OAuth1 Access Tokens

• Clean after (days) -- Expired OAuth1 access tokens are automatically cleaned up after this many days (default: 7).

OAuth2 Bearer Tokens

• Bearer token expiration (seconds) -- How long a bearer token is valid.
• Bearer token auto-vacuum (days) -- Expired tokens are automatically cleaned up after this many days.

Rate Limiting

• Max requests per window -- Maximum number of API requests per time window. Set to 0 to disable rate limiting.
• Window duration (seconds) -- The length of the rate limiting window.

When the limit is exceeded the API returns 429 Too Many Requests.

Configuration File Parameters

It is possible to further customize the API via a set of parameters inside the Odoo configuration file. The following parameters are available:

• rest_default_cors -- Sets the CORS attribute on all REST routes. Default: None
• rest_docs_security_group -- XML ID of an access group to protect the API docs. Default: None
• rest_docs_codegen_url -- URL of the Swagger Codegen service for client generation. Default: https://generator3.swagger.io/api
• rest_authentication_basic -- Enable Basic authentication on the REST API. Default: True
• rest_authentication_oauth1 -- Enable OAuth1 authentication on the REST API. Default: True
• rest_authentication_oauth2 -- Enable OAuth2 authentication on the REST API. Default: True
• rest_db_header -- Custom HTTP header name for the database name. Default: DATABASE
• rest_db_param -- Query parameter name for the database name. Default: db
• rest_logging -- Enable request/response logging. Default: True
• rest_logging_autovacuum -- Days after which log entries are automatically deleted. Default: 30
• rest_logging_attribute_limit -- Character limit for individual attribute values in logged request/response data. Default: 150
• rest_logging_content_limit -- Character limit for logged response content body. Default: 25000
• rest_debug -- Show full tracebacks in API error responses instead of generic messages. Default: False

Parameters from a configuration file can be loaded via the --config command.

Domain

Evaluates a search domain on the configured model. The domain expression supports standard Odoo domain syntax. You can optionally restrict the returned fields by selecting specific fields in the Domain Fields tab. The query parameters limit, offset and order are supported. When the Wrap Response flag is enabled the result is wrapped in an envelope containing the endpoint name, model, domain, result list and count.

Server Action

Executes a linked server action (ir.actions.server). The request parameters are passed as active_id and active_ids in the action context. The return value of the action is sent back as the response.

Python Code

Executes arbitrary Python code via safe_eval. The following variables are available in the evaluation context:

• env -- the current Odoo environment
• model -- a recordset for the configured model
• params -- a dictionary of request parameters
• headers -- the HTTP request headers
• uid / user -- the current user ID / user record
• logger -- a Python logger instance
• time, datetime, dateutil, timezone -- date/time libraries
• json, b64encode, b64decode -- serialization utilities
• make_json_response, make_response -- response helpers
• responses, exceptions -- HTTP status helpers

The code can set one of the following variables to control the response:

• result -- a value that is JSON-serialized and returned
• content -- raw string content returned as-is
• response -- a full Werkzeug Response object

Endpoint Documentation

Each custom endpoint has a Docs tab where you can configure how it appears in the Swagger UI:

• Summary and Description -- displayed in the endpoint listing
• Parameters -- a JSON list of OpenAPI parameter objects
• Responses -- a JSON map of OpenAPI response objects
• Components -- additional OpenAPI schema components
• Default responses -- toggles for standard 200, 400, 401 and 500 responses

Basic Authentication

Send an Authorization header with the Basic scheme. The credentials are username:password (or username:api_key) encoded in Base64.

Example (admin:admin encoded in Base64):

Authorization: Basic YWRtaW46YWRtaW4=

Bearer Authentication

Send an Authorization header with the Bearer scheme using an Odoo API key.

Example:

Authorization: Bearer <api_key>

OAuth1 (RFC 5849)

Three-legged OAuth1 flow using consumer key/secret and request/access tokens. Requires the oauthlib Python library.

1. POST /api/v2/authentication/oauth1/initiate -- Obtain a request token.
2. Redirect user to /api/v2/authentication/oauth1/authorize to log in and grant access.
3. POST /api/v2/authentication/oauth1/token -- Exchange the authorized request token for an access token.

OAuth2 (RFC 6749)

Standard OAuth2 flow with support for all four grant types. Requires the oauthlib Python library.

• Authorization endpoint: /api/v2/authentication/oauth2/authorize
• Token endpoint: /api/v2/authentication/oauth2/token
• Revocation endpoint: /api/v2/authentication/oauth2/revoke

The authentication method used (Basic, OAuth1, OAuth2) is tried in order. The first successful authentication wins. If all methods fail, the API returns 401 Unauthorized.

Swagger UI

The Swagger UI tab shows the full OpenAPI 3.0 specification for all built-in and custom endpoints. From here you can:

• Browse all endpoints grouped by category (Server, Common, Model, File, Report, Security, System, and any custom endpoint tags).
• See request parameters, request bodies and response schemas.
• Authorize using Basic authentication or OAuth2 via the lock icon on each protected endpoint or the global Authorize button.
• Try out any endpoint directly from the browser -- fill in parameters, click Execute and see the live response, curl command and request URL.
• Generate client SDKs in various languages (Python, Java, JavaScript, etc.) using the integrated Swagger Codegen service.

Model Explorer

The Model Explorer tab provides an interactive browser for all Odoo models the current user has read access to. For each model you can:

• See all fields with their type, description, module of origin, required/ readonly flags, relation targets and selection values.
• Browse all public methods with their full signature, parameter details, docstrings, introducing module and API decorators.
• Try methods directly from the UI -- select a method, fill in IDs, args and kwargs, and execute the call. The result or error is displayed inline along with the equivalent curl command.
• Filter and search models by name, and filter fields/methods within a model.

Quick Start Example

The examples below use Basic authentication with admin:admin credentials (Base64-encoded as YWRtaW46YWRtaW4=). Replace the host, credentials and database name with your own values.

Read all partners:

curl -X GET \
  'https://your-odoo.com/api/v2/search_read/res.partner?fields=["name","email"]&limit=5' \
  -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
  -H 'DATABASE: your-database'

Create a new partner:

curl -X POST \
  'https://your-odoo.com/api/v2/create/res.partner' \
  -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
  -H 'DATABASE: your-database' \
  -H 'Content-Type: application/json' \
  -d '{"values": {"name": "Jane Doe", "email": "jane@example.com", "is_company": false}}'

Update a partner:

curl -X PUT \
  'https://your-odoo.com/api/v2/write/res.partner' \
  -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
  -H 'DATABASE: your-database' \
  -H 'Content-Type: application/json' \
  -d '{"ids": [42], "values": {"phone": "+1 555-0123"}}'

Delete a partner:

curl -X DELETE \
  'https://your-odoo.com/api/v2/unlink/res.partner' \
  -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
  -H 'DATABASE: your-database' \
  -H 'Content-Type: application/json' \
  -d '{"ids": [42]}'

Contributors

• Mathias Markl <mathias.markl@mukit.at>

Images

Some pictures are based on or inspired by:

• Font Awesome
• Prosymbols
• Smashicons

Author & Maintainer

This module is maintained by the MuK IT GmbH.

MuK IT is an Austrian company specialized in customizing and extending Odoo. We develop custom solutions for your individual needs to help you focus on your strength and expertise to grow your business.

If you want to get in touch please contact us via mail or visit our website.