API keys
Reference for server-scoped API keys used with the Assistance REST API.
An API key authorizes a service to call the Assistance REST API on behalf of
one server. Keys begin with gt_ and are server-scoped; they do not sign a user
in and cannot be used to create or manage other keys.
Enable advanced options to show API Keys in a server's dashboard navigation.
Authentication
Send the key in the Authorization header:
Authorization: Bearer gt_…The API base URL is https://api.assistance.sh/v1. Older clients may use
Authorization: Guild gt_…, but new integrations should use Bearer.
Creating a key
Create a key from the server's API Keys page. Set a descriptive name, an expiry, and only the scopes the integration needs. The plaintext key appears once, immediately after creation. Store it in your deployment's secret manager before closing the reveal dialog; it cannot be retrieved later.
Every key always includes these read-only scopes:
| Scope | Purpose |
|---|---|
guild.data:get | Read basic data for the authorized server. |
global.token:get | Inspect the current key's metadata. |
All other scopes are opt-in. Scope names follow resource:action, for example:
| Scope | Allows |
|---|---|
guild.members:read | Read server member data. |
guild.alerts:post | Create alerts in the server. |
guild.automations:execute | Run manual-trigger automations. |
guild.templates:send | Send a saved template. |
guild.tickets:create | Create a ticket. |
The generated REST reference lists the required scope for each endpoint.
Expiry, editing, and revocation
Keys can expire after 7, 30, 90, or 365 days, on a custom date, or never. Use a short expiry for temporary integrations and rotate long-lived keys regularly.
You can edit a key's name, scopes, or expiry, but not its plaintext value. If a key is exposed, no longer needed, or belongs to a retired integration, revoke it. Revocation takes effect immediately and cannot be undone; create a new key and update the integration if it still needs access.
Security guidance
- Keep keys in a server-side secret manager, never in browser code, templates, packages, or source control.
- Give each integration its own key and descriptive name so it can be revoked independently.
- Use the smallest scope set that supports the integration.
- Do not confuse a guild API key with an Automation secret. OAuth is currently internal-only.
Most write endpoints are limited to 60 requests per minute per key.
How is this guide?