---
title: "Change the tax IDs an API key reaches"
method: PATCH
path: "/accounts/{account}/api-keys/{api_key}/nif-scope"
tags: ["Account"]
---

# Change the tax IDs an API key reaches

`PATCH /accounts/{account}/api-keys/{api_key}/nif-scope`

## Request

- Base URL: `https://api.factuarea.com/v1`
- URL: `https://api.factuarea.com/v1/accounts/{account}/api-keys/{api_key}/nif-scope`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Replace the tax-ID scope of an API key with `scoped_company_ids`, the complete resulting list (not a delta).
- The new scope can never exceed yours; a scope the plan of any tax ID disallows returns 422.
- Test keys and browser-published keys cannot change scope.
- Uncovered scopes return 403 `insufficient_scope`.

## Path parameters

- `account` string, uuid, required
- `api_key` string, uuid, required

## Headers

- `Idempotency-Key` string
- `Factuarea-Version` string, date

## Request body

- UpdateApiKeyNifScopeV1Request: Replace the scope of an API key of your account. `scoped_company_ids` is the complete resulting list of companies (company IDs, UUID v7), not a delta: at least one, all of them in your account and in the environment of the key, and never beyond the scope of the credential making the request. Every scope the key already has must fit the plan of EVERY company in the new list; otherwise the request returns 422 and nothing changes.
  - `scoped_company_ids` string[], required: Complete resulting list of public identifiers (UUID v7) of the companies of your account the key will reach. It replaces the current scope.

## Response `200`

- object
  - `data` ApiKeyNifScope, required: The tax IDs an API key reaches after changing its scope. The list is the complete resulting scope, not a delta.
    - `id` string, uuid, required: Opaque identifier (UUID v7) of the API key.
    - `object` 'api_key_nif_scope', required: Always `api_key_nif_scope`.
    - `scope` ApiKeyNifScopeItem[], required: Tax IDs the API key reaches, each with its opaque identifier and its fiscal identifier.
      - `id` string, uuid, required: Opaque identifier of the company (UUID v7) — the one the company axis expects in the path.
      - `tax_id` string, required: Spanish fiscal identifier (NIF, CIF, NIE). Structural format: NIF `^\d{8}[A-Z]$`, NIE `^[XYZ]\d{7}[A-Z]$`, CIF `^[A-Z]\d{7}[A-Z0-9]$`. AEAT control-digit (checksum) validation is enforced when the request opts in via the `Factuarea-Version` header on or after the activation version; without that opt-in the legacy permissive behaviour is preserved.
      - `name` string, required
      - `access_level` 'view' | 'operate': Access level the key has on that tax ID: `view` is read-only, `operate` can also write. Present on the scope of an API key.

## Other responses

- `400`: `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version.
- `401`: Missing or invalid API key.
- `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).
- `404`: The requested resource does not exist or belongs to another company. `account_not_found`: the account in the path does not exist or is not the account of the API key.
- `422`: Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters.
- `429`: Rate limit exceeded. Retry after the duration in `Retry-After`.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)