# Context pack: Authentication Source: https://nordvec.com/docs/guides/authentication Pack: https://nordvec.com/docs/packs/authentication This pack bundles one Nordvec guide with the guides it builds on and the guides it links to, in reading order, so an assistant reading it meets no reference it cannot follow. ## Contents 1. [Authentication](https://nordvec.com/docs/guides/authentication) (this guide) --- # Authentication Source: https://nordvec.com/docs/guides/authentication Authenticate API requests with a workspace API key sent as a bearer token, and pick the key class and scopes a job needs. A program calls the Nordvec API with an **API key**, sent as a bearer token in the `Authorization` header. ```bash curl https://nordvec.com/api/v1/documents/list \ -H "Authorization: Bearer $NORDVEC_API_KEY" ``` Not every endpoint takes a key. Conversations, webhooks and key management belong to a signed-in person and answer only to a session; the [API reference](/docs/api) marks each operation with the credentials it accepts. ## Key classes [#key-classes] A key is one of two classes, and its prefix says which: | Class | Prefix | For | | --- | --- | --- | | Client | `nv_eu_live_` | Reading: search, list and fetch documents, quota, audit trail | | Indexing | `nv_eu_idx_` | Writing: push, delete and re-permission documents, check ingestion | ## Scopes [#scopes] A key carries one or more scopes, and an operation answers `403` to a key without the scope it needs. A key can only carry scopes of its own class. | Scope | Class | Allows | | --- | --- | --- | | `search:read` | Client | Search, list, fetch and batch-fetch documents | | `quota:read` | Client | Embedding quota and usage analytics | | `audit:read` | Client | Search the workspace's audit trail and read its event catalogue | | `index:write` | Indexing | Push and bulk-push documents, update their permissions | | `index:delete` | Indexing | Delete pushed documents | | `index:status` | Indexing | Push status and ingestion health | | `index:acl-widen` | Indexing | Make an already-restricted document visible to the whole workspace. A key with this scope must have an expiry | Give each key the fewest scopes its job needs, so a leaked key can do as little as possible. ## Creating a key [#creating-a-key] Create a key under **Settings > API Keys**. Creating one needs the workspace **owner** or **admin** role; on a personal workspace that is you. The **raw key is returned exactly once** and is never retrievable afterwards, so copy it into your secret store straight away. A key belongs to the workspace, not to the person who created it. It reads what the workspace shares: documents a person has connected but not shared stay visible only to that person, and no key can see them. A key does stop working once the person who created it, or last rotated it, leaves the workspace, so a departing admin's keys do not outlive their access; an owner or admin who rotates the key takes it over, and it works again. A key's lifetime is 1 to 365 days, and a key created without one works for 365 days. Rotating a key starts its lifetime again from the day of the rotation. A key can also carry an IP allowlist of up to 50 addresses or CIDR ranges. A key no request authenticates with for 45 days, counted in UTC calendar days, is disabled. After 38 days of disuse, the workspace's owners and admins get a notice naming the key and the date it will be disabled; one request the key authenticates before that date keeps it, and so does rotating it. A key that expires before that date stops working at its expiry instead, and gets no notice unless it has already gone 45 days unused. With no owner or admin left to notify, the key is disabled at 45 days without a notice. A request the key's IP allowlist refuses, or one refused because the key's creator has left, is not authenticated and does not count. A disabled key never works again, so create a new key for any application that still needs one. ## Rotating and revoking [#rotating-and-revoking] Treat an API key like a password. If one leaks, rotate or revoke it immediately. - **Rotate** replaces a key's credential in place. The previous credential keeps working for a grace window you choose: none, 15 minutes, 1 hour, 6 hours or 24 hours (the default), so you can roll the new credential out to your services without downtime. - **Revoke** disables a key immediately; it can no longer authenticate. Both actions require a signed-in session (they are not themselves API-key operations), so a leaked key cannot be used to rotate itself. ## Good practice [#good-practice] - Store keys in a secret manager or environment variable, never in source code. - Use a separate key per service or environment so you can revoke narrowly. - Set an expiry on keys for CI and scripts.