Skip to content

Restricted Keys

When you register with Invoicetronic, you receive a pair of primary keys (test and live) with full access to all API resources. Restricted keys let you create additional keys, ideal for managing multiple integrations or delegating access securely.

Creation and management

Restricted keys are created and managed from the Dashboard, in the Keys section, or through the API with the /subkey endpoint. For each key you can configure:

  • Description — a label to identify the key's purpose
  • Status — enable or disable the key at any time
  • Companies — restrict access to specific companies, or leave empty to allow access to all
  • Permissions — in the Dashboard pick a preset (see below), through the API set the level for each resource
  • CORS Origins — configure allowed origins for browser requests (see the CORS guide)

Each restricted key automatically generates a test and live key pair, just like the primary key. The keys are shown only once, when they are created: see Visibility and regeneration.

Permission presets

Each restricted key has a permission preset that determines which operations it can perform:

Preset Description
Full access Read and write on all endpoints. Equivalent to the primary key (except for restricted key management itself)
Read only Read-only operations (GET) on all endpoints. Ideal for monitoring or reporting integrations
Send Read permissions on all endpoints, plus the ability to send invoices. Ideal for integrations that need to issue documents but not manage other resources

No preset includes key management: a restricted key cannot create, update or delete other keys. Through the API, instead of presets you set permissions resource by resource (see Permissions).

Company restrictions

If your primary key manages multiple companies, you can create restricted keys that only have access to some of them. This is useful when:

  • You have different clients and want to give each one a key that only accesses their own documents
  • You want to isolate environments between departments or different integrations
  • You need to delegate access to external collaborators, limiting it to the relevant companies

If you don't select any company, the key will have access to all companies on your account, including the ones created later.

A key limited to some companies only sees the data of those companies: sent and received invoices, status updates, exports, webhooks and their history, and log events (plus its own calls). It can manage only webhooks bound to one of its companies: a webhook without a company would receive the events of the whole account.

Managing keys through the API

With the primary key you can manage restricted keys directly through the API, without going through the Dashboard. This is the way for integrators that onboard their own customers automatically.

Method Endpoint Description
GET /subkey List of restricted keys, paginated. Filters: company_id, active, q (description)
GET /subkey/{id} A single key
POST /subkey Creates a key. The response contains test_key and live_key
PUT /subkey Updates description, status, permissions, companies and CORS origins. Replaces every field: omitted permissions, company_ids or cors_origins mean none
DELETE /subkey/{id} Deletes the key, which stops working at once
POST /subkey/{id}/roll Regenerates the keys (see Visibility and regeneration)

These endpoints answer only to the primary key: a restricted key gets 403 with code = subkey_not_allowed.

Onboarding a customer in two calls

Create the customer's company, then a key limited to that company:

# 1. Create the company (primary key)
curl -X POST https://api.invoicetronic.com/v1/company/ \
  -u ik_live_YOUR-API-KEY: \
  -H "Content-Type: application/json" \
  -d '{"vat": "IT01234567891", "fiscal_code": "01234567891", "name": "Studio Rossi Srl"}'
# → { "id": 42, ... }

# 2. Create the restricted key limited to the company
curl -X POST https://api.invoicetronic.com/v1/subkey/ \
  -u ik_live_YOUR-API-KEY: \
  -H "Content-Type: application/json" \
  -d '{
        "description": "Studio Rossi Srl",
        "company_ids": [42],
        "permissions": {"company": "Read", "send": "Write", "receive": "Read", "update": "Read", "status": "Read"}
      }'
# → { "id": 318, "test_key": "ik_test_…", "live_key": "ik_live_…", ... }

Hand the keys in the response to your customer: they can operate only on their own company. A few things to know:

  • if the VAT number is already registered under another account, step 1 fails with code = company_already_registered: ask support for a transfer;
  • to receive incoming invoices, the customer still has to register the recipient code on the Agenzia delle Entrate portal (see Agenzia delle Entrate);
  • operations performed with restricted keys use the credits of your account.

Permissions

Through the API, permissions are set per resource in the permissions object. A missing resource means no access.

Resource Read Write
company list and read companies also create, update and delete them
send list and read sent invoices also send and validate invoices
receive list and read received invoices also delete them
webhook list and read webhooks also create, update and delete them
update, log, webhookhistory, export, status read —

Rules:

  • each permission cannot exceed the one of the primary key (400, code = permission_exceeds_parent);
  • on creation, if you omit permissions the key gets the permissions of the primary key, copied at that moment: if the primary key's permissions change later, the key does not follow;
  • the ids in company_ids must belong to your account (400, code = company_not_found);
  • an account can hold up to 1,000 restricted keys (400, code = subkey_limit_reached).

Visibility and regeneration

For security, the keys of a restricted key (both test and live) are shown only once: in the creation response, in the Dashboard right after creating it, and after every regeneration. They cannot be read afterwards: copy them and store them somewhere safe right away.

If you lose a key, or suspect it was exposed, regenerate it: from the Dashboard with the Regenerate button, or through the API with POST /subkey/{id}/roll. The restricted key keeps its id, permissions, companies and CORS origins; only the test and live keys change.

The replaced keys stop working at once. To migrate without downtime you can keep them valid for a while: in the Dashboard with Keep the current secrets working for 24 hours, through the API with expires_in_hours (1 to 168 hours). Meanwhile both the old and the new keys work.

Keys created before this change

Restricted keys created before one-time visibility was introduced stay visible in the Dashboard as before. The primary key is always visible.

Use cases

  • Least-privilege integration: create a read-only key for a reporting system that only needs to query invoices and logs
  • External collaborator: create a temporary key restricted to specific companies for a consultant or developer
  • Dedicated microservice: assign each service in your architecture a key with only the necessary permissions
  • Development and testing: create test keys with reduced permissions for your development environments
  • Frontend/browser application: if you call the API from JavaScript in the browser, the key is inevitably visible in the client code. Use a restricted key with the minimum required permissions and configure the allowed CORS origins from the Dashboard. See the CORS guide for more details
  • ISV with Desk: assign each client a restricted key limited to their company only, and let them use Desk directly with that key. Each client will have exclusive access to their own documents, with full autonomy and security

Desk seats

A Desk seat grants access to Desk Cloud for a specific live API key. Seats are independent subscriptions, each with its own billing cycle.

Sandbox (test) keys do not require a seat: they work in Desk for free, with no time limit. Use them to try Desk or for development and testing.

How it works

  1. In the Keys section of the Dashboard, click Enable Desk on any live key (primary or restricted)
  2. Complete the checkout
  3. The key is now linked to a Desk seat. Your client (or yourself) can register on Desk, enter the key, and start using it immediately

Managing seats

From the Keys page you can:

  • Enable Desk — purchase a new seat for a key
  • Move Desk — reassign an existing seat to a different key (same subscription, no new checkout)
  • Disable Desk — cancel the seat's subscription

Each seat is tied to a single key (1:1). A key can have at most one seat, and a seat is assigned to exactly one key at a time.

For ISVs

If you are an ISV serving multiple clients:

  1. Create a restricted key per client (with company restrictions for isolation), from the Dashboard or through the API
  2. Purchase a Desk seat for each key
  3. Share the key with your client — they register on Desk and enter it in their profile

You control access centrally: disable or move seats at any time from the Dashboard. Your clients never deal with billing — you manage everything.

Security

Restricted keys follow the principle of least privilege: always assign only the permissions that are strictly necessary. You can disable or delete a restricted key at any time, from the Dashboard or through the API, with immediate effect, and regenerate it if it was exposed.

Best practice

Avoid sharing your primary key. Instead, create dedicated restricted keys for each integration or collaborator, so you can revoke access individually without impacting other integrations.