Skip to main content
An API key lets your code, or an AI assistant, call Valendata as you. Each key carries scopes: it can do only what its scopes allow, so a leaked key that can only read a skill cannot run one. This page covers managing keys in the app. How to send a key, and the full list of scopes, are in Authentication and scopes.

​
Create an API key

1

Open API Keys settings

Go to app.valendata.com and navigate to Settings → API Keys.
2

Create a new key

Click Create key. A dialog asks for a name, the scopes, and an expiry.
3

Name your key

Enter a descriptive name that identifies where this key will be used — for example, Production Server, Zapier Integration, or CI Pipeline. A clear name makes it easy to audit and revoke the right key later.
4

Pick the scopes and expiry

Tick only what this integration needs (see Scopes). The default is Read skills, Invoke skills, and Read runs: enough to run skills and read their results. Pick an expiry (7, 30, or 90 days, 1 year, or never). An expired key stops working, like a revoked one.
5

Limit it to some skills or workflows (optional)

Under Limit to, pick the skills and/or workflows this key may use. Leave a list empty to allow all. See Limit a key to some skills or workflows.
6

Copy the key immediately

After creation, Valendata shows the full key value once. Copy it now.
This is the only time the secret value is displayed. Valendata does not store it in recoverable form. If you lose it, you must revoke the key and create a new one.
7

Store the key securely

Paste the key into an environment variable or a secrets manager. Never put it in source files.
Keys created before scopes existed show a Full access badge. They keep every scope, so nothing that used them breaks. Replace them with scoped keys when you can.

​
Limit a key to some skills or workflows

A key can also be limited to a list of skills (allowed_skill_ids) and a list of workflows (allowed_workflow_ids). The two limits are separate: a key limited to some skills can still run every workflow unless you also pick workflows, and the other way round. An empty list means no limit. The keys list shows a N skills only or N workflows only badge on a limited key. Using it on anything else returns 403:
The limits apply to every API route for that skill or workflow, including its runs and schedules, and to the MCP tools: a limited key only sees the skill_<slug> and workflow_<slug> tools it may use.

​
Create a key from code

A signed-in session can create a key with POST /api/keys. Leave out scopes to get the default set. allowed_skill_ids limits the key to those skills only, and allowed_workflow_ids to those workflows only (up to 200 each). An id you cannot use returns 422. The 201 response holds the key in raw_key. It is returned only this once.

​
Use your API key

Send it in the Authorization: Bearer header. See Authentication and scopes. Keep it in an environment variable or a secrets manager, never in source code. Add .env to .gitignore.

​
Revoke an API key

To permanently invalidate a key:
  1. Go to Settings → API Keys.
  2. Find the key by its name and the prefix shown in the Key column.
  3. Click the trash icon on that row.
  4. Confirm when prompted.
Revocation is immediate. All subsequent requests using the revoked key return 401 Unauthorized. So do requests with an expired key.

​
Best practices

One key per integration

Create a separate key for each service or environment (production, staging, CI). This lets you revoke a single integration without disrupting others.

Least privilege

Give each key only the scopes it needs, and an expiry. A dashboard that only reads results needs skills:read and runs:read, nothing that spends credits.

Rotate keys regularly

Issue a new key, update your integration, verify it works, then revoke the old key. Rotate after any team member offboarding.

Never commit to source control

Store keys in environment variables or a secrets manager. Use .gitignore and pre-commit hooks to prevent accidental commits.

Audit from the dashboard

The API Keys settings page lists every key by name, prefix, creation date, and last used date. Review it periodically and revoke any key no longer in use.

​
Frequently asked questions

Revoke it immediately from Settings → API Keys and create a replacement. Check your run history for any unexpected activity.
There is no hard limit on the number of keys. Creating one key per integration is a recommended practice, not a forced constraint.
The key itself has no cost. Credits are used by the runs and other work the key starts.