---
title: "Authentication | Nuvio Docs"
description: "Authenticate every request with an API key from your Nuvio company."
url: https://nuvio.io/docs/api/authentication
---

# Authentication

The Nuvio API uses API keys to authenticate requests. Send the key in the `Authorization` header as a bearer token:

`Authorization: Bearer <api_key>`

A key belongs to the Nuvio company it was created in, not to a person: every request made with it reads or writes that company's records. Each key carries scopes, and an endpoint answers only a key that has its scope.

Keep your keys secret. Don't put them in code that runs in a browser or an app, or in a public repository; read them from an environment variable on your server instead. The examples here use `NUVIO_API_TOKEN`.

## Create an API key

Owners and Company Admins of a company can create its keys in Nuvio:

1.  In Nuvio, open **Settings** › **Company** › **Developers**.
2.  Under **API Keys**, choose **Add New API Key**.
3.  Give the key a name that says where it's used, such as the app or service that will call the API.
4.  Select the scopes it needs (see below), then choose **Save**.
5.  Copy the key and store it somewhere safe. Nuvio shows it only once: after you close the window, it can't be shown again.

To revoke a key, choose **Delete** next to it on the same page. Requests made with it are refused from then on. If a key may have leaked, delete it and create a new one.

## Scopes

Give each key only the scopes its integration needs. A request with a key that lacks the endpoint's scope gets `403` with error `1001`.

-   `read`

    Read records: every GET endpoint, and the expense and income lists.

    Show 17 endpoints Hide endpoints

    -   [GET `/v1/transactions` List all Transactions](https://nuvio.io/docs/api/list-transactions)
    -   [GET `/v1/transactions/{id}` Get a Transaction by ID](https://nuvio.io/docs/api/get-transaction)
    -   [GET `/v1/accounts` List all Bank Accounts](https://nuvio.io/docs/api/list-bank-accounts)
    -   [GET `/v1/accounts/{id}` Get a Bank Account by ID](https://nuvio.io/docs/api/get-bank-account)
    -   [GET `/v1/business-entities` List all Customers or Suppliers](https://nuvio.io/docs/api/list-business-entities)
    -   [GET `/v1/business-entities/{id}` Get a Customer or Supplier by ID](https://nuvio.io/docs/api/get-business-entity)
    -   [POST `/v1/list-expenses` List all expenses](https://nuvio.io/docs/api/list-expenses)
    -   [GET `/v1/expense/{id}` Get an Expense by ID](https://nuvio.io/docs/api/get-expense)
    -   [POST `/v1/list-incomes` List all incomes](https://nuvio.io/docs/api/list-incomes)
    -   [GET `/v1/income/{id}` Get an Income by ID](https://nuvio.io/docs/api/get-income)
    -   [GET `/v1/product-services` List all Products & Services](https://nuvio.io/docs/api/list-products)
    -   [GET `/v1/product-services/{id}` Get a Product / Service by ID](https://nuvio.io/docs/api/get-product)
    -   [GET `/v1/project` List all Projects](https://nuvio.io/docs/api/list-projects)
    -   [GET `/v1/project/{id}` Get a Project by ID](https://nuvio.io/docs/api/get-project)
    -   [GET `/v1/tags` List all Tags](https://nuvio.io/docs/api/list-tags)
    -   [GET `/v1/tags/{id}` Get a Tag by ID](https://nuvio.io/docs/api/get-tag)
    -   [GET `/v1/tax` Tax List](https://nuvio.io/docs/api/list-taxes)

-   `write`

    Create records, and record or match payments.

    Show 10 endpoints Hide endpoints

    -   [POST `/v1/transactions` Add a new Transaction](https://nuvio.io/docs/api/create-transaction)
    -   [POST `/v1/accounts` Create a new Bank Account](https://nuvio.io/docs/api/create-bank-account)
    -   [POST `/v1/business-entities` Create a new Customer or Supplier](https://nuvio.io/docs/api/create-business-entity)
    -   [POST `/v1/expense` Create a new Expense](https://nuvio.io/docs/api/create-expense)
    -   [POST `/v1/income` Create a new Income](https://nuvio.io/docs/api/create-income)
    -   [POST `/v1/add-payment` Record a new payment](https://nuvio.io/docs/api/add-payment)
    -   [POST `/v1/match-payment/{transactionId}` Match payment with an existing Transaction](https://nuvio.io/docs/api/match-payment)
    -   [POST `/v1/product-services` Create a new Product or Service](https://nuvio.io/docs/api/create-product)
    -   [POST `/v1/project` Create a new Project](https://nuvio.io/docs/api/create-project)
    -   [POST `/v1/tags` Create a new Tag](https://nuvio.io/docs/api/create-tag)

-   `update`

    Change existing records: every PUT endpoint.

    Show 8 endpoints Hide endpoints

    -   [PUT `/v1/transactions/{id}` Update Transaction](https://nuvio.io/docs/api/update-transaction)
    -   [PUT `/v1/accounts/{id}` Update Bank Account](https://nuvio.io/docs/api/update-bank-account)
    -   [PUT `/v1/business-entities/{id}` Update Customer or Supplier](https://nuvio.io/docs/api/update-business-entity)
    -   [PUT `/v1/expense/{id}` Update expense](https://nuvio.io/docs/api/update-expense)
    -   [PUT `/v1/income/{id}` Update income](https://nuvio.io/docs/api/update-income)
    -   [PUT `/v1/product-services/{id}` Update Product or Service](https://nuvio.io/docs/api/update-product)
    -   [PUT `/v1/project/{id}` Update Project](https://nuvio.io/docs/api/update-project)
    -   [PUT `/v1/tags/{id}` Update Tag](https://nuvio.io/docs/api/update-tag)

## When authentication fails

`401`

No usable `Authorization: Bearer <api_key>` header. Error code `1002`.

`403`

The key is unknown or deleted, or lacks the scope the endpoint needs. Error code `1001`.

Authenticated request

```
curl https://api.nuvio.io/v1/tax \
  -H "Authorization: Bearer $NUVIO_API_TOKEN"
```

Your API key

Create a key in Nuvio under **Settings › Company › Developers**, then set it in your environment:

`export NUVIO_API_TOKEN=<api_key>`

The key is shown once. Store it in a secret manager or your server's environment, never in client code.