Service accounts

A service account is a Katla team member that is not a person. It gets an API key instead of a login, so your platform — a CI pipeline, a provisioning job, an internal dashboard — can call the Katla API without a human signing in and without anyone sharing their own credentials.

Service accounts are available on the Business and Custom plans. On other plans the endpoints below return 403 SERVICE_ACCOUNTS_REQUIRE_PLAN.

How it differs from the MCP server

The MCP server acts as you: it runs an OAuth flow in a browser, and everything it does is attributed to your user account. That is right for an AI assistant and wrong for a server, which has no browser and should not be borrowing a person’s identity. A service account is its own identity. It is bound to one team, carries its own role and scopes, and keeps working when the person who created it leaves.

Create one

From Team settings → API keys in the dashboard, or through the API as a team admin:

curl -X POST https://api.katla.app/teams/$TEAM_ID/service-accounts \
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy pipeline",
    "role": "member",
    "scopes": ["katla:read", "katla:write"],
    "expiresInDays": 365
  }'

{
  "serviceAccount": { "id": "…", "name": "Deploy pipeline", "role": "member", "…": "…" },
  "key": { "id": "…", "maskedKey": "katla_sk_••••••••a1b2", "…": "…" },
  "apiKey": "katla_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

apiKey is returned once and never again — Katla stores only a SHA-256 hash of it. Put it straight into your secret store. If it is lost, issue a new key and revoke the old one.

Use it

Send the key as a bearer token, exactly where a user access token would go:

curl https://api.katla.app/teams/$TEAM_ID/sites \
  -H "Authorization: Bearer $KATLA_API_KEY"

Every endpoint that accepts a user token accepts a service-account key, with the exceptions listed under What a service account cannot do.

Roles and scopes

A service account has both, and both are enforced on every request.

Role	What it can reach
`member`	Read and operate the team’s sites, scans, cookies and consent records
`admin`	The above, plus team-level site management

owner is not assignable. An owner can transfer or delete the team, which is not something a credential sitting in a CI runner should be able to do.

Scope	What it allows
`katla:read`	`GET` requests only
`katla:write`	Everything the role allows, including writes

A key without katla:write gets 403 INSUFFICIENT_SCOPE on any non-GET request. Issue read-only keys wherever the integration only reports — a dashboard, an alerting job — so a leak cannot change anything.

What a service account cannot do

The boundary is deliberate: a service account operates your sites and compliance data; it cannot administer your account. It is refused, with 403 SERVICE_ACCOUNT_FORBIDDEN, on:

Billing — plans, payment methods, invoices, cancellation
Team members — inviting, removing, or listing people
Team lifecycle — creating, renaming, transferring, or deleting a team
Google Tag Manager connection, which needs a human at a Google consent screen
Service accounts themselves, including issuing further keys

That last one is the important one. A credential that can mint credentials turns a single leaked key into permanent access that outlives revoking the key that leaked. A key is also bound to one team for its whole life. Naming a different team’s id in a URL returns 403, not that team’s data.

Rotate without downtime

An account can hold more than one live key, which is what makes rotation a deploy rather than an outage:

# 1. Issue a second key
curl -X POST https://api.katla.app/teams/$TEAM_ID/service-accounts/$ACCOUNT_ID/keys \
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" -d '{"expiresInDays": 365}'

# 2. Deploy the new key everywhere it is used, then revoke the old one
curl -X DELETE https://api.katla.app/teams/$TEAM_ID/service-accounts/$ACCOUNT_ID/keys/$OLD_KEY_ID \
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN"

Revoke

Revoking the account withdraws every key under it at once — use this if a machine is decommissioned or you suspect a compromise:

curl -X DELETE https://api.katla.app/teams/$TEAM_ID/service-accounts/$ACCOUNT_ID \
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN"

Revocation takes effect on the next request. Revoked accounts stay in the list rather than disappearing, so the record of what existed and when it was withdrawn survives an incident.

Keeping keys safe

Store them as secrets. A katla_sk_ key is a password. Never commit one, and never put one in frontend code — the API refuses cross-origin browser calls, so a key in a browser is exposed without even working.
Give each integration its own account. Then revoking one does not break the others, and lastUsedAt tells you which integrations are actually live.
Prefer read-only. Most integrations only report.
Set an expiry. expiresInDays puts an upper bound on the damage from a key nobody remembers.

Rate limits

Every credential gets its own budget, so one key cannot spend another’s — or yours.

Caller	Limit
A service-account key	600 requests/minute, per key
A signed-in user	600 requests/minute
Unauthenticated	120 requests/minute, per IP
Issuing a key	10/hour

Over the limit you get 429 with code: RATE_LIMIT_EXCEEDED, a retryAfterSeconds field, and a standard Retry-After header — back off on that rather than retrying immediately. X-RateLimit-Remaining tells you how much budget is left before you get there. Because the budget is per key, rotating a leaked key also gives the replacement a clean slate rather than inheriting whatever the old one spent.

Reference

All routes require a team admin and the Business or Custom plan.

Method	Path
`GET`	`/teams/:teamId/service-accounts`
`POST`	`/teams/:teamId/service-accounts`
`PATCH`	`/teams/:teamId/service-accounts/:serviceAccountId`
`DELETE`	`/teams/:teamId/service-accounts/:serviceAccountId`
`POST`	`/teams/:teamId/service-accounts/:serviceAccountId/keys`
`DELETE`	`/teams/:teamId/service-accounts/:serviceAccountId/keys/:keyId`

Errors

Code	Meaning
`401`	The key is unknown, expired, or revoked
`403 SERVICE_ACCOUNTS_REQUIRE_PLAN`	The team is not on Business or Custom
`403 INSUFFICIENT_SCOPE`	The key lacks `katla:write` for a write request
`403 SERVICE_ACCOUNT_FORBIDDEN`	An account-administration route, which machines cannot reach
`429 RATE_LIMIT_EXCEEDED`	Over the budget for this key; wait for `Retry-After`

Getting started

Guides

Reference

Compliance

Service accounts

How it differs from the MCP server

Create one

Use it

Roles and scopes

What a service account cannot do

Rotate without downtime

Revoke

Keeping keys safe

Rate limits

Reference

Errors

​How it differs from the MCP server

​Create one

​Use it

​Roles and scopes

​What a service account cannot do

​Rotate without downtime

​Revoke

​Keeping keys safe

​Rate limits

​Reference

​Errors

How it differs from the MCP server

Create one

Use it

Roles and scopes

What a service account cannot do

Rotate without downtime

Revoke

Keeping keys safe

Rate limits

Reference

Errors