Skip to main content
Deel

Deel API token for Odoo: create it, scope it and paste it

Deel has three kinds of API token and the Odoo connector uses one: the organization token, which a Deel admin creates in Deel's Developer Center. Here is the walkthrough, the scope Deel's reference lists for each call the connector makes, where the token goes in Odoo and what happens to it when you save.

FlexigoTech · Editor in charge: Víctor Gómez · Updated 18 November 2026

Key facts

Module
Deel
Versions
Odoo 17, 18, 19 and 20
Checked
in the connector's source code, version 20.0 · against the sources linked at the end
Reading time
7 min

The Deel token Odoo needs

Deel has three tokens: the organization token, which stands for the whole organization; the personal token, which stands for one user; and the worker token, which stands for one EOR employee. The connector works with the organization token, which is the default under Auth Method: Organization token. According to Deel's help center, a personal token expires if the person who created it leaves the company, while an organization token is not tied to anyone and does not expire, although it cannot sign contracts. To create one you have to be an Org Admin or IT Developer Admin in Deel.

Step by step in Deel's Developer Center

  1. Open the Developer Center. Deel's authentication guide gets there through More and then Developer; its webhooks guide, through the profile icon, Settings and Developer Center; and its help center, through Apps & Integrations.
  2. Open the Access Tokens tab and click Generate new token.
  3. Pick the Organization token type.
  4. Tick the scopes in the table below and decide which sensitive data the token can reach.
  5. Click Generate and copy the token right away: Deel warns that you cannot see it again afterwards.

Deel issues separate keys for its sandbox and for production, and asks you not to mix them. In Odoo, the connection's Environment field offers Production and Sandbox (tests), which is a Deel demo organization (demo.deel.com) with no real money. The token has to belong to the environment you pick.

Which scopes to tick

Deel names its scopes resource:read and resource:write, and its reference gives the scope each call needs. These are, among others, the calls the connector makes and the scope of each one according to Deel's reference on 18-11-2026:

What forCallScope
Test connectionGET /organizationsorganizations:read
Legal entitiesGET /legal-entitiesorganizations:read, accounting:read
Contracts and peopleGET /contracts, GET /peoplecontracts:read, people:read
Invoices, Deel fees and their PDFsGET /invoices, GET /invoices/deel, GET /invoices/{id}/downloadaccounting:read
Payments and their breakdownGET /payments, GET /payments/{payment_id}/breakdownaccounting:read
Payroll cycles and cost centersGET /legal-entities/{legal_entity_id}/payroll-events, GET /legal-entities/{legal_entity_id}/cost-centerslegal-entity:read
Gross-to-net report of each cycleGET /reports/payroll/cycles/{cycle_id}/gross-to-netpayslips:read
Registering and removing the webhookPOST /webhooks, DELETE /webhooks/{id}webhooks:write
Sending cost centers to DeelPOST /legal-entities/{legal_entity_id}/cost-centers/synchronizelegal-entity:write

The last two rows write to Deel. The webhook is only registered when an admin clicks Register webhook, and cost centers only travel to Deel if you choose to have Odoo lead them; the default is that they go from Deel to Odoo. The help text of the token field asks for read scopes. With only those, according to its reference, Deel will refuse to register the webhook and, if you choose to have Odoo lead cost centers, to take them too. Deel's authentication guide gives two possible answers for a token that lacks a scope: 403 or 401. On a 403, the sync every 30 minutes keeps reading everything else. On a 401, the connector takes it as a refused token and, if Odoo leads cost centers, every run stops there, before contracts, invoices, payments and payroll; in that case the token also needs legal-entity:write. If Deel changes the scope of a call, its reference wins.

Where it goes in Odoo

In the Deel connection, an admin:

  • ticks I accept that FlexigoTech Cloud keeps the Deel credential, because until then the token field cannot be filled in and nothing is sent;
  • leaves Organization token under Auth Method and picks the Environment;
  • pastes the token into Deel organization token and saves.

On save, the connector sends the token to FlexigoTech Cloud, which has to be on trial or subscribed, and records the date under Credential saved on. The field shows up empty again, on purpose: it is write-only and Odoo does not keep the token. Only an admin can save it. After that, Test connection asks Deel for the organization and its legal entities and answers with the name and how many there are.

Deel connection in Odoo with the organization token method selected, the FlexigoTech Cloud consent accepted, the token field empty and the date the credential was saved
The connection with the token already saved: the field is empty and the date says when it was sent (made-up organization, demo data).

If you change the Environment or the Auth Method of a saved connection, the saved credential stops counting: the connection goes back to Not connected, you paste the token again and the old entry is deleted from FlexigoTech Cloud.

Where the token goes

According to the module itself, FlexigoTech Cloud keeps the token encrypted, one entry per connection, and puts it on each call to Deel as an Authorization: Bearer header, which is how Deel says to use it. Calls to Deel do not leave your Odoo directly; the only thing going the other way is the webhook notices, which Deel sends to your Odoo and which are covered in Deel webhooks with Odoo. Disconnect deletes the token from FlexigoTech Cloud and, while the service is active, the webhook from Deel, and leaves everything already synced alone.

FlexigoTech Cloud settings in Odoo with the database connected and the Deel connector card on trial, with the text about the calls it sends to Deel
The Deel connector in the FlexigoTech Cloud settings, on trial; its card text says what it sends to Deel and that the token is kept encrypted (demo data).

Deel recommends keeping credentials in a secure vault and never in code, rotating tokens every quarter or when someone leaves the team, and deleting the ones nobody uses. With the connector, rotating means creating the new token in Deel, pasting it into the same field, saving, and deleting the old one in Deel.

Authorize with Deel, today

The other Auth Method option, Authorize with Deel, connects without copying a token: a Deel admin approves the FlexigoTech app. As long as FlexigoTech Cloud does not have that app for the chosen environment, the connector answers "Authorize with Deel is not available yet for this Deel environment. Use an organization token meanwhile: nothing was sent to Deel."

Limits and errors

Deel allows 5 requests per second per organization, across all its tokens, in a rolling 1-second window, and its sandbox has the same limits. Above that it answers 429 and, according to its documentation, sends no headers that warn you first. If another program reads the same organization, it shares those 5 with the connector. The sync leaves at least 0.25 seconds between one call and the next; on a 429 it waits (one second, unless the answer asks for another wait, and never more than 5), retries up to 3 times and, if it still fails, leaves it for the next run.

Deel's answerCause, according to DeelWhat the connector does
401Token invalid or expired, no Authorization header, or missing the required scopesSets the connection to Deel refused the token and asks for a new one
403The token lacks the scope for that callDoes not treat the token as bad: it shows the reason Deel gives
429More than 5 requests per second in the organizationWaits and retries

A note in the connector's code adds another 403, "Error 1010": Deel's Cloudflare blocking the Python-urllib User-Agent, which is why the connector always sends its own. To see why Deel refused a call, the Request logs in the Developer Center keep 15 days of requests made with the organization's tokens, rejected ones included, with the reason.

What was tested

The connector works on Odoo 17, 18, 19 and 20, on your own server or on Odoo.sh, and not on Odoo Online. It was tested end to end against a Deel demo organization (demo.deel.com), through FlexigoTech Cloud: the connection, legal entities, a contract with its person and vendor, webhooks and a second sync without duplicates. Invoices, payments and payroll cycles were tested with answers modelled on Deel's API reference, because that organization had none yet. What comes in afterwards as a vendor bill is in the Deel invoice guide, and the comparison with Deel's own integrations, in Deel integrations. The connector is explained in full on its page and published on Odoo Apps.

Keep reading

Deel webhooks with Odoo: signature, events, retries and what the connector doesHow Deel signs each webhook, which events its list has, when it retries or disables a webhook, and what FlexigoTech's Deel connector for Odoo does with them.Deel invoice in Odoo: from the Deel invoice to the vendor billWhat a Deel invoice for a contractor, an EOR employee or a Deel fee carries, and how it reaches Odoo as a vendor bill with its VAT, PDF and cost centers.Deel accounting integrations: what GL Sync and Bill Sync do and how to get them in OdooDeel connects its accounting data to NetSuite, Xero, QuickBooks, Sage, SAP and Dynamics. Odoo is not on that list: what a connector covers and what it does not.
Checked in the connector's source code (version 20.0) and the linked sources

Sources