Browse the docsAPI keys and scopes

API keys and scopes

An API key lets your own code, a script or a tool like Zapier act on your Kadens account. You create it in the dashboard, choose exactly what it may do, and send it with every request.

5 min

On this page

What an API key is
Create a key
Send your key
Test your key
Scopes
Rotate and revoke
Errors
Best practices
What now?

What an API key is

A key is a secret that belongs to one account. Every request made with it acts as that account and can only do what the key's scopes allow.

Every key starts with kad_ followed by 43 random characters. The prefix makes a key easy to spot if it ends up somewhere it should not be.

Claude and ChatGPT do not need a key: they connect by signing in from the AI assistants page. Use a key for scripts, automation tools and anything else that sends a header.

Create a key

Open API keys in your dashboard
Go to the API keys section of your integrations and choose Issue new key.
Name it and choose its scopes
Give the key a name you will recognise later, pick only the scopes it needs, and optionally set it to expire after 1 to 365 days.
Copy the key and store it safely
The key is shown once. Copy it into your password manager or your server's environment right away: Kadens cannot show it again.

Create your first key

Opens the dashboard page where your keys live.

Open API keys

Send your key

Send the key in the Authorization header of every request, as a Bearer token.

Request header

Authorization: Bearer kad_...

Keep the key out of your code: store it in an environment variable such as KADENS_API_KEY. Every sample in these docs reads it from there.

Test your key

The quickest way to check a key works: ask the API who it belongs to.

Check your key from a terminal

Set the two environment variables above, then run this command. A working key answers with its account and its scopes.

Bash

1
2
curl "$KADENS_API_URL/v1/me" \
  -H "Authorization: Bearer $KADENS_API_KEY"

Response

1
2
3
4
5
6
7
8
9
10
11
{
  "entity": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "Barcelona Salsa Studio"
  },
  "apiKeyId": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "scopes": [
    "webhooks.read",
    "webhooks.write"
  ]
}

Scopes

A scope is one permission. A key can only do what its scopes allow, so give each key the fewest scopes it needs. A write scope never includes the matching read scope.

AI assistants that sign in get fewer scopes

Scopes marked API key only are never given to an assistant that connects by signing in. They can only be granted to a key you create yourself.

Website

Scope	Description
`site.read`	Read site contentView the pages, blocks and settings of your sites.
`site.design_reference.submit`	Submit design referencesUpload screenshots and layouts for the site builder to use as styling guidance.
`site.generate`	Generate site draftsCreate new draft pages and blocks with the AI site builder.API key only
`site.compose`	Compose site layoutsAdd, reorder and remove blocks on a draft.
`site.theme.configure`	Configure the site themeChange the colors, fonts and spacing a draft is styled with.API key only
`site.preview.read`	Read site previewsOpen a preview of a draft before it goes live.
`site.publish`	Publish sitesMake a draft live on your public site.
`embed.read`	Read embedded widgetsView your embeddable widgets, their stats, the websites they were seen on and the domains allowed to show them.
`embed.write`	Manage embedded widgetsCreate, edit and archive embeddable widgets, and add or remove the domains allowed to show them.

Catalogue

Scope	Description
`catalog.read`	Read your catalogueList your courses, their editions and the plans and prices you sell them with.
`catalog.course.write`	Create coursesAdd a course to your catalogue, with its title, summary and lessons.
`catalog.plan.write`	Set plan pricesCreate or change the prices on a subscription plan you own.
`media.import`	Import mediaFetch a video from a public URL into your media library.
`schedule.write`	Set your availabilityCreate or replace the weekly availability schedule bookings are offered from.
`events.read`	Read eventsView your events, their sessions and ticket types.
`events.write`	Manage eventsCreate and change your events, their sessions and ticket types.
`schedule.read`	Read your scheduleView your class schedule, its sessions and the calendar feeds you publish.
`schedule.manage`	Manage your scheduleCreate, change and cancel the classes, sessions and calendar feeds on your schedule.

Sales

Scope	Description
`orders.read`	Read ordersView your orders, payments and refunds.
`subscriptions.read`	Read subscriptionsView the subscriptions to your plans and their status.
`bookings.read`	Read bookingsView the bookings for your classes and sessions.
`payouts.read`	Read payoutsView your payouts and your balance.
`pricing.write`	Manage pricing and discountsCreate and change discounts, add-ons, offers and the rules that decide who can buy what.
`orders.write`	Manage orders and refundsChange orders and issue refunds. A refund moves money back to the buyer.
`payments.write`	Manage paymentsChange payment settings, wallets and how your account collects payments. This can move money.
`insights.read`	Read insightsView your statistics and dashboard figures.

People

Scope	Description
`attendees.read`	Read attendeesView who holds tickets to your events and their check-ins.
`enrollments.read`	Read enrollmentsView who is enrolled in your courses and their progress.
`people.read`	Read personal dataSee the names, email addresses and other personal details of your customers. Without this permission they are hidden.
`people.write`	Manage customersAdd and change the people in your CRM, their access and their requests.
`attendees.write`	Check in attendeesCheck attendees in and out of your events and sessions.

Webhooks

Scope	Description
`webhooks.read`	Read webhooksView your webhook endpoints, their delivery log and the event catalog.
`webhooks.write`	Manage webhooksCreate, edit and remove webhook endpoints, rotate their secrets, and send, resend or replay events.

Access control

Scope	Description
`permissions.policy.read`	Read permission policiesView what each role is allowed to do across your profile.
`permissions.policy.write`	Change permission policiesGrant and withdraw what each role is allowed to do across your profile.API key only
`actions.delegate`	Act on your behalfLet the assistant run any action you can do in Kadens on your behalf, limited by the other permissions you grant.

Learning

Scope	Description
`learning.read`	Read learning recordsView exams, marks, certificates, practice submissions and student progress.
`learning.write`	Manage learningMark exams, release results, issue certificates and review practice submissions.

Community

Scope	Description
`community.read`	Read your communityView your community, announcements, chats, reviews and FAQs.
`community.write`	Manage your communityPost announcements, answer chats and moderate your community, reviews and FAQs.

Marketing

Scope	Description
`marketing.read`	Read marketingView your mailings, reminders, affiliates and rewards.
`marketing.write`	Manage marketingCreate and send mailings, set up reminders and manage affiliates and rewards.

Settings

Scope	Description
`terms.read`	Read your account termsView the commission, limits and trial period agreed for your account.
`settings.read`	Read settingsView your profile, tags, integrations and account settings.
`settings.write`	Change settingsChange your profile, tags, integrations and account settings.

Rotate and revoke

Topic	Description
`Reissue`	Creates a new key with the same name, scopes and expiry. The old key stops working immediately, so update it wherever it is used.
`Revoke`	Disables the key immediately. Any integration using it stops working. This cannot be undone.
`Expiry`	A key created with an expiry stops working on that date. A key without one works until you revoke it.
`Last used`	The dashboard shows when each key was last used. A key nobody has used in a long time is a good candidate to revoke.

Errors

The status code tells your integration what to do next.

Status	Meaning
`401`	The key is missing, badly formatted, revoked or expired. Check the Authorization header, or create a new key.
`403`	The key works but lacks the scope this request needs. Reissuing keeps the same scopes, so create a key with the missing scope instead.

Error response

1
2
3
4
5
6
7
{
  "statusCode": 403,
  "message": "API key missing required scope",
  "timestamp": "2026-10-01T10:00:00.000Z",
  "path": "/api/v1/me",
  "requestId": "req_7c1e0b"
}

Best practices

Use keys only on a server. Never put one in a web page, a mobile app or anything a visitor can download.
Store keys in environment variables or a secrets manager, never in source code or a repository.
Give each key only the scopes it needs, and prefer read scopes when the integration only reads.
Create one key per integration, so you can revoke one without breaking the others.
If a key may have leaked, reissue or revoke it straight away.

What now?

Open in dashboard

Was this helpful?

Can't find what you're looking for?Search againTalk to us

{ "entity": { "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f", "name": "Barcelona Salsa Studio" }, "apiKeyId": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "scopes": [ "webhooks.read", "webhooks.write" ] }

Scope

Description

site.read

Read site contentView the pages, blocks and settings of your sites.

site.design_reference.submit

Submit design referencesUpload screenshots and layouts for the site builder to use as styling guidance.

site.generate

Generate site draftsCreate new draft pages and blocks with the AI site builder.API key only

site.compose

Compose site layoutsAdd, reorder and remove blocks on a draft.

site.theme.configure

Configure the site themeChange the colors, fonts and spacing a draft is styled with.API key only

site.preview.read

Read site previewsOpen a preview of a draft before it goes live.

site.publish

Publish sitesMake a draft live on your public site.

embed.read

Read embedded widgetsView your embeddable widgets, their stats, the websites they were seen on and the domains allowed to show them.

embed.write

Manage embedded widgetsCreate, edit and archive embeddable widgets, and add or remove the domains allowed to show them.

Scope

Description

catalog.read

Read your catalogueList your courses, their editions and the plans and prices you sell them with.

catalog.course.write

Create coursesAdd a course to your catalogue, with its title, summary and lessons.

catalog.plan.write

Set plan pricesCreate or change the prices on a subscription plan you own.

media.import

Import mediaFetch a video from a public URL into your media library.

schedule.write

Set your availabilityCreate or replace the weekly availability schedule bookings are offered from.

events.read

Read eventsView your events, their sessions and ticket types.

events.write

Manage eventsCreate and change your events, their sessions and ticket types.

schedule.read

Read your scheduleView your class schedule, its sessions and the calendar feeds you publish.

schedule.manage

Manage your scheduleCreate, change and cancel the classes, sessions and calendar feeds on your schedule.

Scope

Description

orders.read

Read ordersView your orders, payments and refunds.

subscriptions.read

Read subscriptionsView the subscriptions to your plans and their status.

bookings.read

Read bookingsView the bookings for your classes and sessions.

payouts.read

Read payoutsView your payouts and your balance.

pricing.write

Manage pricing and discountsCreate and change discounts, add-ons, offers and the rules that decide who can buy what.

orders.write

Manage orders and refundsChange orders and issue refunds. A refund moves money back to the buyer.

payments.write

Manage paymentsChange payment settings, wallets and how your account collects payments. This can move money.

insights.read

Read insightsView your statistics and dashboard figures.

Scope

Description

attendees.read

Read attendeesView who holds tickets to your events and their check-ins.

enrollments.read

Read enrollmentsView who is enrolled in your courses and their progress.

people.read

Read personal dataSee the names, email addresses and other personal details of your customers. Without this permission they are hidden.

people.write

Manage customersAdd and change the people in your CRM, their access and their requests.

attendees.write

Check in attendeesCheck attendees in and out of your events and sessions.

Scope

Description

webhooks.read

Read webhooksView your webhook endpoints, their delivery log and the event catalog.

webhooks.write

Manage webhooksCreate, edit and remove webhook endpoints, rotate their secrets, and send, resend or replay events.

Scope

Description

permissions.policy.read

Read permission policiesView what each role is allowed to do across your profile.

permissions.policy.write

Change permission policiesGrant and withdraw what each role is allowed to do across your profile.API key only

actions.delegate

Act on your behalfLet the assistant run any action you can do in Kadens on your behalf, limited by the other permissions you grant.

Scope

Description

learning.read

Read learning recordsView exams, marks, certificates, practice submissions and student progress.

learning.write

Manage learningMark exams, release results, issue certificates and review practice submissions.

Scope

Description

community.read

Read your communityView your community, announcements, chats, reviews and FAQs.

community.write

Manage your communityPost announcements, answer chats and moderate your community, reviews and FAQs.

Scope

Description

marketing.read

Read marketingView your mailings, reminders, affiliates and rewards.

marketing.write

Manage marketingCreate and send mailings, set up reminders and manage affiliates and rewards.

Scope

Description

terms.read

Read your account termsView the commission, limits and trial period agreed for your account.

settings.read

Read settingsView your profile, tags, integrations and account settings.

settings.write

Change settingsChange your profile, tags, integrations and account settings.

Topic

Description

Reissue

Creates a new key with the same name, scopes and expiry. The old key stops working immediately, so update it wherever it is used.

Revoke

Disables the key immediately. Any integration using it stops working. This cannot be undone.

Expiry

A key created with an expiry stops working on that date. A key without one works until you revoke it.

Last used

The dashboard shows when each key was last used. A key nobody has used in a long time is a good candidate to revoke.

Status

Meaning

401

The key is missing, badly formatted, revoked or expired. Check the Authorization header, or create a new key.

403

The key works but lacks the scope this request needs. Reissuing keeps the same scopes, so create a key with the missing scope instead.

Open API keys in your dashboard

Name it and choose its scopes

Copy the key and store it safely

Create your first key

Check your key from a terminal

AI assistants that sign in get fewer scopes

Website

Catalogue

Sales

People

Webhooks

Access control

Learning

Community

Marketing

Settings

What now?

Open API keys in your dashboard

Name it and choose its scopes

Copy the key and store it safely

Create your first key

Check your key from a terminal

AI assistants that sign in get fewer scopes

Website

Catalogue

Sales

People

Webhooks

Access control

Learning

Community

Marketing

Settings

What now?