> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nelkap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys and secrets

> The two values your app uses to talk with Nelkap, and how to limit, rotate, and revoke them.

Your app and Nelkap prove who they are to each other with two values. Each one works in a single direction:

| Value | Who sends it | What it proves | Where your app reads it |
| - | - | - | - |
| API key | Your app, on every request to Nelkap | The request comes from your app, for this project. | `NELKAP_API_KEY` |
| Project secret | Nelkap, on every call to your endpoint | The call comes from Nelkap. | `NELKAP_SECRET` |

Keep both on the server, in your host's environment variables or a secrets manager. Never put them in code that runs in a browser.

## API keys

An API key lets your app start runs, emit events, register workflows, and save steps, all in one project. A project can have up to 10 API keys, so each app or each server can have its own.

### Create a key

Go to API keys and create one. A key takes:

* A name, up to 256 characters, that says where it's used, like `production servers`.
* A project. Its endpoint must be set first, since a key is what lets your app start runs.
* Allowed IPs, if you want: up to 20 addresses or ranges, like `203.0.113.7` or `203.0.113.0/24`, in IPv4 or IPv6. Requests from any other address are turned down with `ipNotAllowed`. Leave it empty to accept requests from anywhere.
* An expiry date, if you want. After that date, the key is turned down with `apiKeyInvalid`.

You can reveal a key's value at any time, to copy it into your app's environment.

### Change or revoke a key

Edit a key to change its name, its allowed IPs, or its expiry date. The change applies to the next request.

Delete a key to revoke it. Requests using it are turned down at once with `apiKeyInvalid`, so put the new key in place first.

### Replace a key without downtime

1. Create a new key in the same project.
2. Set it as `NELKAP_API_KEY` in your app, and deploy.
3. Once every instance of your app runs with the new key, delete the old one.

Runs in progress aren't affected: each request uses the key your app has at that moment.

## The project secret

Every project has one secret. Nelkap sends it in the `Authorization` header of each call to your endpoint, and `handle` compares it with `NELKAP_SECRET`. A call without the right secret gets a `401`, and no workflow runs.

You can reveal the secret from your project at any time.

### Rotate the secret

Rotate the secret if it leaked. The old one stops working at once, and your endpoint turns every call away until it has the new one:

1. Rotate the secret from your project, and copy the new one.
2. Set it as `NELKAP_SECRET` in your app, and deploy right away.

Calls turned away in the meantime are tried again, up to three attempts in about three minutes. A run whose attempts all fail shows `deliveryFailed`: [replay it](https://docs.nelkap.com/monitor/runs.md#replay-a-run) once the new secret is live.

## Who can do what

| Action | Role |
| - | - |
| See API keys and projects | Reader and above |
| Create, change, reveal, and delete API keys | Member and above |
| Reveal a project's secret | Member and above |
| Rotate a project's secret | Admin and owner |

See [Members and roles](https://docs.nelkap.com/manage/members.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.