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

# API keys

> Authenticate with the Nylio public API using API keys instead of OAuth tokens.

# API keys

API keys let you authenticate with the Nylio public API without going through an OAuth flow. They are useful for scripts, CI pipelines, and backend integrations where browser-based login is not practical.

## Create an API key

1. Open the [API access page](https://nylio.app/app/developer/api-keys) in the Nylio app.
2. Click **Create key**.
3. Give the key a name, choose which scopes to grant, and set an expiration period.
4. Copy the key immediately. It is only shown once.

### Expiration options

| Option        | Duration                          |
| ------------- | --------------------------------- |
| 30 days       | Key expires after 30 days         |
| 90 days       | Key expires after 90 days         |
| 1 year        | Key expires after 365 days        |
| No expiration | Key does not expire automatically |

### Available scopes

| Scope            | Access                                       |
| ---------------- | -------------------------------------------- |
| `workspace:read` | List workspaces                              |
| `document:read`  | Read and export documents                    |
| `document:write` | Create, edit, and replace personal documents |
| `search:read`    | Search documents                             |

## Use an API key

Pass the key in the `x-api-key` header:

```bash theme={null}
curl https://api.nylio.app/api/public/v1/documents \
  -H "x-api-key: YOUR_API_KEY"
```

API keys work with the public API endpoints allowed by their scopes. If a required scope is missing, the request returns `403 insufficient_scope`.

<Warning>
  Do not send both a bearer token and an `x-api-key` header in the same request. The API rejects requests that include both.
</Warning>

## Manage existing keys

From the [API access page](https://nylio.app/app/developer/api-keys) you can:

* Disable a key temporarily without deleting it.
* Re-enable a disabled key.
* Revoke a key permanently.

## Best practices

* Name keys after the integration they power.
* Use the shortest expiration period that fits the use case.
* Grant only the scopes each integration needs.
* Rotate keys periodically and remove unused keys.
* Store keys in environment variables or a secrets manager, not in source control.