Add Administration docs group (DEL-32733) (#264) · speechmatics/docs@447861b · GitHub
Skip to content

Commit 447861b

Browse files
petemomoclaude
petemomo
and
claude
authored
Add Administration docs group (DEL-32733) (#264)
## What Adds a new top-level **Administration** navigation group to the docs, covering 13 pages that document the self-serve portal. Ticket: https://speechmatics.atlassian.net/browse/DEL-32733 ## Structure Administration is a navigation-group label only (no landing page), placed between **Deployments** and **Developer Resources**: - **Accounts** - **Workspaces** (sub-group): Workspaces concepts · Manage members · Domain verification · Single sign-on (SSO) - **Projects** · **API keys** · **Management tokens** - **Billing** · **Plans** · **Usage** - **Regions** · **Security and compliance** All 13 pages live flat in `docs/administration/` (URLs `/administration/<page>`); the Workspaces grouping is expressed in `sidebar.ts` only and does not change URLs. ## Notes for reviewers - Pages were validated against the project style guide, terminology, and product architecture. - Intra-group and cross-section links were normalized to **site-relative paths** (e.g. `/administration/projects`, `/api-ref/management/create-an-api-key`) so they are covered by the broken-link check (`onBrokenLinks: "throw"`). - `npm run build` passes with no broken links; `cspell` and `biome` are clean. - A few figures (Pro 6,000 h/mo cap, 20%/33% discounts, region availability) should get a final product check before publishing. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Pete Mo <175202887+cabbage-ice-cream@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 5e8b255 commit 447861b

15 files changed

Lines changed: 667 additions & 0 deletions

‎docs/administration/accounts.mdx‎

Lines changed: 45 additions & 0 deletions

‎docs/administration/api-keys.mdx‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: API keys
3+
description: Create, view, and revoke the API keys that authenticate your applications to Speechmatics.
4+
---
5+
6+
# API keys
7+
8+
An API key authenticates requests to the Speech to Text and Text to Speech APIs. Each key is scoped to a single [project](/administration/projects): it can access only the transcripts produced within that project. For how keys are used in requests, see [Authentication](/get-started/authentication).
9+
10+
API keys differ from [management tokens](/administration/management-tokens). API keys authenticate transcription and synthesis requests and are scoped to a project. Management tokens authenticate workspace administration and are scoped to the workspace.
11+
12+
## Create an API key
13+
14+
API keys are created within your active project. To create a key in a different project, switch projects first. See [Projects](/administration/projects#switch-between-projects).
15+
16+
1. Go to **API keys** in the sidebar under **Projects**.
17+
2. Click **Create new key**.
18+
3. Enter a descriptive name for the key.
19+
4. Click **Generate new key**.
20+
5. Copy the key value from the dialog.
21+
22+
:::warning
23+
You cannot access the key value again after closing this dialog. Store it in a secure location immediately.
24+
:::
25+
26+
## Revoke an API key
27+
28+
Revoking a key disables it immediately. Requests made with the key are rejected, which may break any application that depends on it.
29+
30+
1. Go to **API keys** in the sidebar under **Projects**.
31+
2. Click the delete button next to the key.
32+
3. Confirm the removal.
33+
34+
## Manage API keys with the API
35+
36+
You can manage API keys programmatically with the Management API, authenticated with a [management token](/administration/management-tokens). Available operations include:
37+
38+
- [Get all API keys](/api-ref/management/get-all-api-keys)
39+
- [Create an API key](/api-ref/management/create-an-api-key)
40+
- [Delete an API key](/api-ref/management/delete-an-api-key)
41+
42+
## API key best practices
43+
44+
- **Use descriptive names.** Name keys after the application or environment that uses them, so you can audit and revoke the right key later.
45+
- **Scope keys to projects.** Create keys in the project that matches their purpose to keep transcripts and usage isolated.
46+
- **Rotate keys periodically.** Create a replacement key, update your application, then revoke the old one.
47+
- **Revoke unused keys.** Remove any key that is no longer in use.
48+
49+
## Next steps
50+
51+
- [Authentication](/get-started/authentication): how to use API keys in requests.
52+
- [Projects](/administration/projects): scope keys by creating them in the right project.
53+
- [Management tokens](/administration/management-tokens): automate key management programmatically.

‎docs/administration/billing.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: Billing
3+
description: Manage your Pro payment card, and view and download invoices.
4+
---
5+
6+
# Billing
7+
8+
On the Billing page you add or manage your payment card and review what you have been charged. Free users add a card here to upgrade to Pro. Managing billing requires the Admin role.
9+
10+
:::info
11+
Enterprise billing is handled through a contract, not a payment card. The card and invoices described here apply to the Pro plan only. See [Enterprise](/administration/plans#enterprise).
12+
:::
13+
14+
## Add or edit a payment card
15+
16+
Adding a card upgrades a Free plan to Pro. See [Plans](/administration/plans).
17+
18+
1. Go to **Billing** in the sidebar under **Workspace**.
19+
2. In the **Payment method** section, click **Add payment card**, or **Edit payment information** if you already have a card.
20+
3. Enter your card details.
21+
4. Save your changes.
22+
23+
## Remove a payment card
24+
25+
:::warning
26+
Removing your payment card downgrades your plan to Free. Usage beyond the Free allowance stops being available.
27+
:::
28+
29+
1. In the **Payment method** section, click the delete icon next to your card.
30+
2. Confirm the removal.
31+
32+
## Invoices and payments
33+
34+
The **Payments** section lists each billing period with its usage, cost, and status. Pro plans are billed on the first of each month for the previous month's usage. For how charges are calculated, see [Plans](/administration/plans#upgrade-to-pro).
35+
36+
A billing period has one of the following statuses:
37+
38+
- **Paid.** The charge has been settled.
39+
- **Due.** The charge is outstanding.
40+
- **Skipped.** No charge was raised for the period.
41+
42+
To view and download the invoice for a period, click the link icon at the end of its row.
43+
44+
## Next steps
45+
46+
- [Plans](/administration/plans): how Free, Pro, and Enterprise billing works.
47+
- [Usage](/administration/usage): see a detailed breakdown of usage by mode and model.

‎docs/administration/domain-verification.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Domain verification
3+
description: Verify a domain so users from your organization join your workspace automatically.
4+
---
5+
6+
# Domain verification
7+
8+
Once a domain is verified, anyone signing up with an email address on that domain is added to your workspace as a Member. Domain verification requires the Admin role.
9+
10+
## Verify a domain
11+
12+
1. Go to **Manage workspace** in the sidebar under **Workspace**.
13+
2. In the **Domain** section, click **Add domain**.
14+
3. Enter the domain you want to verify.
15+
4. Add the DNS TXT record shown to your domain's DNS settings.
16+
5. Return to the portal and click **Verify**.
17+
18+
DNS propagation can take up to 24 hours. The domain status changes to **Verified** once the record is detected.
19+
20+
## Remove a verified domain
21+
22+
1. In the **Domain** section, click the delete icon next to the verified domain.
23+
2. Confirm the removal.
24+
25+
Removing a domain stops new automatic joins. Existing members keep their access.
26+
27+
## Next steps
28+
29+
- [Manage members](/administration/manage-members): invite users manually or change their roles.
30+
- [Single sign-on (SSO)](/administration/sso): configure SSO for your workspace.

‎docs/administration/manage-members.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Manage members
3+
description: Invite users to your workspace, change their roles, and remove access.
4+
---
5+
6+
# Manage members
7+
8+
Member management requires the Admin role. See [Workspaces concepts](/administration/workspaces-concepts#roles) for what each role can do.
9+
10+
## Invite a user
11+
12+
1. Go to **Manage workspace** in the sidebar under **Workspace**.
13+
2. In the **Users** section, click **Invite user**.
14+
3. Enter the user's email address.
15+
4. Select a role: **Admin** or **Member**.
16+
5. Click **Invite**.
17+
18+
The invited user receives an email with a link to complete their account. Until they accept, they will not appear as an active member.
19+
20+
## Change a user's role
21+
22+
1. In the **Users** table, click the options menu (⋯) next to the user.
23+
2. Select **Edit role**.
24+
3. Choose the new role and confirm.
25+
26+
## Remove a user
27+
28+
Removing a user revokes their access to the workspace immediately. Any API keys they created stay in the workspace and continue to work, because keys belong to the workspace rather than the user. Revoke them separately if needed. See [API keys](/administration/api-keys).
29+
30+
1. In the **Users** table, click the options menu (⋯) next to the user.
31+
2. Select **Remove user**.
32+
3. Confirm the removal.
33+
34+
## Next steps
35+
36+
- [Domain verification](/administration/domain-verification): let users from your organization join automatically.
37+
- [Single sign-on (SSO)](/administration/sso): configure SSO for your workspace.

‎docs/administration/management-tokens.mdx‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: Management tokens
3+
description: Automate workspace administration with tokens that create projects and manage API keys programmatically.
4+
---
5+
6+
# Management tokens
7+
8+
## How management tokens work
9+
10+
Management tokens authenticate programmatic access to workspace administration. Use them to automate project creation, API key management, and other workspace operations through the Management API.
11+
12+
Tokens are scoped to the workspace and do not expire unless you revoke them. Each token can be assigned a subset of permissions, so you can limit access to only what your automation requires.
13+
14+
### Permissions
15+
16+
| Permission | Description |
17+
|---|---|
18+
| View projects | View projects created within your workspace. |
19+
| Manage projects | Manage, edit, and delete projects in your workspace. |
20+
| View API keys | View API keys generated in your workspace. |
21+
| Delete API keys | Delete API keys in your workspace. |
22+
| Create API key | Create API keys in your workspace. |
23+
24+
## Create a management token
25+
26+
1. Go to **Manage workspace** in the sidebar under **Workspace**.
27+
2. In the **Management tokens** section, click **+ Create management token**.
28+
3. Enter a descriptive name for the token.
29+
4. Select the permissions your automation needs.
30+
5. Click **Create management token**.
31+
6. Copy the token value from the **Save your key** dialog.
32+
33+
:::warning
34+
You cannot access the token value again after closing this dialog. Store it in a secure location immediately.
35+
:::
36+
37+
## View token details
38+
39+
1. In the **Management tokens** table, click the options menu (⋯) next to the token.
40+
2. Select **View details**.
41+
42+
The details panel displays the token name, key prefix, last used timestamp, assigned permissions, and creation date.
43+
44+
## Revoke a management token
45+
46+
Revoking a token disables it immediately. API requests made with the token are rejected, which may break any systems that depend on it.
47+
48+
:::danger
49+
Revoking a management token cannot be undone.
50+
:::
51+
52+
1. In the **Management tokens** table, click the options menu (⋯) next to the token.
53+
2. Select **Revoke key**.
54+
3. Review the token name and key in the confirmation dialog.
55+
4. Click **Revoke key** to confirm.
56+
57+
## Management token best practices
58+
59+
- **Limit permissions.** Assign only the permissions each token needs. A token that creates API keys does not need permission to delete them.
60+
- **Use descriptive names.** Name tokens after their purpose or the system that uses them, such as `ci-pipeline` or `key-rotation-script`. This makes it easier to audit and revoke the right token later.
61+
- **Rotate tokens periodically.** Create a replacement token, update your systems, then revoke the old one.
62+
- **Revoke unused tokens.** Check the **Last used** column regularly. Revoke any token that has never been used or has not been used recently.
63+
64+
## Next steps
65+
66+
- [Create an API key](/api-ref/management/create-an-api-key): Management API reference for creating keys programmatically.
67+
- [Projects](/administration/projects): create and manage projects.
68+
- [API keys](/administration/api-keys): how API keys differ from management tokens.

‎docs/administration/plans.mdx‎

Lines changed: 57 additions & 0 deletions

0 commit comments

Comments
 (0)