---
title: "Authentication"
description: "How to send your Nodu API key with a request, what a 401 or 403 response means, and how to keep API keys safe."
url: "/guides/api-basics/authentication/"
index: "/llms.txt"
---

# Authentication

Every request to the Nodu API carries an API key. You send it in a header. When the key is missing or not valid, Nodu refuses the request. [Environments and API keys](/guides/get-started/environments-and-api-keys/index.md) explains how you get a key from Nodu and which key to use in each environment.

## Send the API key

Send the key in the `Authorization` header, as a bearer token:

```text
Authorization: Bearer <your-api-key>
```

For example, this call lists your transfers in the sandbox, the test environment:

```bash
curl https://api.sandbox.nodu.fi/v1/transfers \
  --header 'Authorization: Bearer <your-api-key>'
```

Send every request over HTTPS. Nodu rejects requests made over plain HTTP.

## When Nodu refuses a request

| Status | Meaning | What you do |
|---|---|---|
| `401 Unauthorized` | The `Authorization` header is missing or is not a bearer token, or the key is not valid in the environment you called. | Check that you send the header and that the key is complete. Check that the key belongs to the environment of the base URL: a sandbox key does not work in production, and a production key does not work in the sandbox. |
| `403 Forbidden` | Nodu recognized the key but does not allow this request. One cause is a request from an IP address that is not allowed for the key. Another is `code=access_denied`: the API key is not allowed to make this request. | Send the request from an address that the key allows. For `access_denied`, contact Nodu. For other causes, read the `code` field of the response. |

Do not send a refused request again unchanged. Check the API key, request and source IP address before you retry.

Both responses carry the error object that every failed request returns. A `401` response has no `code` field. [Errors and rule codes](/guides/api-basics/errors-and-rule-codes/index.md) describes the object and the other statuses.

## Keep API keys safe

An API key gives full access to the Nodu API in its environment. Anyone who holds the key can read your customers' data and create transfers.

- Call the Nodu API from your backend only. Do not put a key in a web page, in a mobile app, or in any other code that runs on a customer's device.
- Store keys in a secret manager or in protected server configuration. Keep them out of source code, logs, support tickets and chat messages.
- Give a key only to the systems and the people that need it.
- Use sandbox keys for development and testing. Use production keys only in your production systems.
- If a key may have been exposed, stop using it. Ask Nodu for a new key before you send more requests.

## Next steps

- [Environments and API keys](/guides/get-started/environments-and-api-keys/index.md): the base URLs, and how you get a key from Nodu.
- [Idempotency](/guides/api-basics/idempotency/index.md): send a `POST` request again without repeating the operation.
- [Errors and rule codes](/guides/api-basics/errors-and-rule-codes/index.md): the error object and what each status means.
- [Quickstart: your first sandbox transfer](/guides/get-started/quickstart/index.md): use a sandbox key from the first request to a completed test transfer.
