API keys

An API key lets code that runs outside a Neural Studio runtime act as you: the Python SDK on your laptop or a cluster, ns sync, and the ns command that relays SSH. Inside a runtime you do not need one; the kernel and terminal carry a narrower session key of their own.

Creating a key

Settings → API Keys → Create key. Give it a name of 1 to 64 characters and an expiration: No expiration, 30 days, 60 days, 90 days or 1 year. The key is shown exactly once, on creation; the list afterwards shows only its name, its first characters, its status and when it was created. Copy it straight into the place the SDK reads it from:

export NEURAL_STUDIO_API_KEY=ns_...
# or, persistently:
mkdir -p ~/.config/neural-studio
printf 'api_key = "ns_..."\n' > ~/.config/neural-studio/config.toml

Keys start with ns_ followed by about 32 URL-safe characters. The platform stores only a hash and the first 12 characters, so a lost key cannot be recovered, only replaced. An account holds at most 10 active keys; revoke one from the same page to make room. Revoke takes effect at once, and an expired key is refused the same way.

What a key can reach

Every key you create has the full_access scope. The name is historical: it is full access to the surfaces that accept keys, not to everything a signed-in browser can do.

Works with a keySign-in only
Creating runs and streaming metrics, logs, artifacts and media (ns.init, ns sync)Launching, stopping or restarting a runtime
Reading runs, metrics, logs, artifacts and mediaFiles and notebooks
The compute catalog and your account's launch limitsEnvironments and builds
SSH tickets and the ssh-config block (ns ssh)Workspaces, members, sharing
Secrets, SSH keys, API keys themselves, billing, account settings

Within those surfaces a key sees exactly what you see: your workspaces, your role in each. A run can be created only in a workspace you belong to.

The session key a runtime holds is narrower still: it can only create and feed runs in its own workspace and fetch the session's own secrets. It cannot read runs elsewhere, open SSH, or manage anything, and it is revoked within a minute of the runtime stopping.

Sending a key

curl -H "Authorization: Bearer ns_..." https://api.neuralstudio.co/api/compute/options
curl -H "X-API-Key: ns_..."            https://api.neuralstudio.co/api/compute/options

Either header works; the SDK uses X-API-Key. A key in a URL query string or a request body is refused with 400 and never evaluated. Requests are limited to 200 a minute per identity, so a key shares the budget with your browser session; over that the API answers 429 with a Retry-After header.

Runtime port hosts (https://<port>-<runtime-id>.run.neuralstudio.co) do not accept API keys; see Web apps on runtime ports for the sign-in they use.

Keeping it safe

  • A key is a password. Keep it in NEURAL_STUDIO_API_KEY or the config file, never in a notebook cell, a repository or an environment spec. On the platform, a token your code needs belongs in Workspace Secrets.
  • Give keys an expiry and a name that says where they live, so revoking the right one is easy.
  • Your keys are deleted with your account.