Authentication and scopes

Send your key

Create a key in Settings → API Keys (see API keys). Keys start with vd_sk_. Send it in either header:

Authorization: Bearer vd_sk_YOUR_API_KEY

x-api-key: vd_sk_YOUR_API_KEY

The examples in these docs read the key from the VALENDATA_API_KEY environment variable:

export VALENDATA_API_KEY="vd_sk_YOUR_API_KEY"

Reading a public skill (GET /v1/skills/{slug} and its health) needs no key.

Scopes

A key can only do what its scopes allow. An AI assistant connected with OAuth gets the scopes you tick on the consent screen; some scopes come with others, some are opt-in under Optional extra access (never granted by default), and some can only be put on an API key (see the last column).

Scope	What it allows	Spends credits?	AI assistants (OAuth)
`skills:read`	List skills, read a skill, its health, versions, and schedule.	No	On the consent screen
`skills:invoke`	Run a skill, and stop your skill runs. For an AI assistant (OAuth) it also allows creating and improving skills (`create_skill`, `get_skill_creation`, `list_skill_creations`, `improve_skill`, `get_skill_improvement`).	Yes	On the consent screen
`skills:write`	Create, update, delete, and improve skills. Restore and pin versions. Schedule skills.	Yes	Opt-in: “Create, edit and delete your skills” under Optional extra access. Editing, deleting, and scheduling skills need it.
`runs:read`	Read and list skill runs.	No	Comes with `skills:read`
`workflows:read`	List workflows, read a workflow, its runs, and its schedule.	No	On the consent screen
`workflows:invoke`	Run a workflow, stop your workflow runs, and switch a workflow schedule on.	Yes	On the consent screen
`workflows:write`	Create, update, and delete workflows and their schedules.	No	Opt-in: “Create, edit and delete your workflows and schedules” under Optional extra access
`account:read`	Read your credit balance, plan, and usage.	No	Opt-in: “See your credits balance and usage” under Optional extra access
`logins:write`	Save, change, and delete logins, and pick the login a skill signs in with.	No	API keys only
`logins:use`	Run skills that sign in with your saved login, and send a run a sign-in code. Without it a run never signs in.	No	Comes with `skills:invoke`
`webhooks:read`	Read your webhook signing secret.	No	API keys only
`webhooks:write`	Rotate your webhook signing secret.	No	API keys only
`knowledge:read`	Read your knowledge base (MCP only).	No	On the consent screen
`knowledge:write`	Save facts to your knowledge base (MCP only).	No	On the consent screen

The /v1 routes that change, delete, or schedule a skill take API keys; an AI assistant reaches them through the MCP tools, with skills:write. An assistant only sees the MCP tools its scopes allow; see Which tools the assistant sees. A new key gets skills:read, skills:invoke, and runs:read unless you pick others. A key made before scopes existed has every scope. A key can also be limited to some skills or workflows. See API keys.

When it fails

Status	Why
`401`	The key is missing, malformed, revoked, or expired. `code` is `unauthorized`.
`403`	The key is valid but lacks a scope, or is limited to other skills or workflows. `code` is `permission_denied`; `detail` names what is missing.

{
  "detail": "This API key is missing the 'skills:invoke' scope. Create a key with 'skills:invoke' in Settings → API keys.",
  "code": "permission_denied",
  "type": "permission_error",
  "request_id": "3f9a1c2b7d4e"
}

Every request made with a key counts against that key’s rate limit, and the response says how much is left. See Rate limits. All other errors are on Errors and limits.

Overview

Skills

Runs

Skill versions

Improvements

Schedules

Workflows

Logins

Account and usage

Webhooks

Authentication and scopes

Send your key

Scopes

When it fails

​Send your key

​Scopes

​When it fails

Send your key

Scopes

When it fails