Get started

Service accounts

Issue and govern API keys for servers, automation, and AI agents

Overview

A key authenticates a caller. Speechify has two kinds, managed from the same place in the Console:

Personal keyService-account key
Belongs toA specific userA service account (a machine identity, not a person)
Use it forYour own scripts and experimentsServers, CI, automation, and AI agents
Survives if the creator leavesNo — tied to the userYes — owned by the account, not a person
ScopesFull account accessA least-privilege ceiling you set on the account
RotationManual recreateZero-downtime rotation with a grace window

Use a service account for anything that runs without a human signed in. It keeps the credential’s identity, permissions, and lifecycle independent of any individual user.

Service accounts as machine identities

A service account is a named identity for a workload — billing-sync, support-bot, nightly-batch. It owns its keys, so:

  • Attribution survives rotation. Usage and spend roll up to the service account across every key it has ever held, so you always know which workload spent what.
  • It is not tied to a user. Deleting the user who created it does not break the workload. Deleting the service account immediately revokes everything it owns.

Create service accounts and their keys under the Service accounts tab in the Console. Key creation and management is console-only; there is no public key-management endpoint.

Scopes (least privilege)

You set a scope ceiling on the service account, and its keys inherit it. Grant only what the workload needs:

ScopeGrants
audio:allGenerate speech (TTS)
voices:readList and read voices
voices:writeCreate and update voices
voices:allAll voice operations
agent:allManage voice agents
conversation:allRead and manage conversations

A TTS-only worker should hold audio:all and nothing more. Editing the account’s scopes propagates to every key that inherits the ceiling, so you tighten or widen a workload’s permissions in one place.

Prefer the narrowest scope that works. A leaked key can only ever do what its scopes allow, so a tightly-scoped key is a much smaller blast radius.

Rotating keys

Rotate a key without downtime: rotation issues a new key and keeps the old one valid for a grace window you choose, so you can roll out the new secret before the old one stops working.

  1. Rotate the key in the Console and copy the new secret.
  2. Deploy the new secret to your workload.
  3. The old key keeps working until the grace window ends, then stops automatically. Set the grace window to 0 to cut over immediately.

Rotate on a schedule, and immediately if a key may have leaked.

Short-lived keys for agents

For agent and AI workloads, hand each session a credential scoped to just that task and expiring on its own — no long-lived skeleton key, no manual cleanup.

A service-account key that is designated as a minter (an option set when you create the key in the Console) can mint a strictly-weaker, shorter-lived child of itself by calling POST /v1/auth/service-account-keys with its own bearer token:

Mint a short-lived key
$curl -X POST https://api.speechify.ai/v1/auth/service-account-keys \
>  -H "Authorization: Bearer $MINTER_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "ttl_seconds": 3600,
>    "scopes": ["audio:all"],
>    "name": "agent-session-42"
>  }'

The response returns the new key’s plaintext once. The request body:

FieldRequiredNotes
ttl_secondsYesLifetime in seconds. Must be 1–86400 (≤ 24 hours). The key expires on its own when the TTL elapses.
scopesNoA subset of the minting key’s scopes. Requesting any scope the minter lacks is rejected. Omit it to pin the child to the minter’s current scopes.
nameNoA label to identify the minted key.

Four rules bound minting:

  • Attenuation — a minted key can never have more access than the key that minted it.
  • Self-expiring — every minted key has a required TTL, capped at 24 hours, and expires with no manual revocation.
  • Depth-1 — only a designated minter can mint, and minted children can never mint again, so a leaked ordinary key can never spawn keys.
  • Same identity — a minted key is an ordinary key under the same service account, so usage and spend still roll up to that account.

Revoking a minter does not revoke keys it already minted — they expire within their TTL (≤ 24 hours). To revoke everything immediately, delete the service account, which cascade-revokes all of its keys at once.

Security best practices

Service-account keys grant API access at your expense. Treat them like passwords — store them in a secret manager, never in client-side code or version control.

  • Give each workload its own service account so attribution and revocation stay isolated.
  • Scope each account to the minimum it needs.
  • Rotate keys on a schedule, and immediately on suspected leak.
  • For agents, prefer short-lived minted keys over a single long-lived key.

See Authentication for how to send keys and the full secret-management guidance.