--- title: "Working with Tokens" description: "Learn how to manage plugin tokens with our API, enabling you to add or remove domains, update permissions, and streamline access control for application." url: https://docs.topol.io/email-editor/guide/adding-tokens-on-demand.html --- # Adding tokens on demand **The token management API lets you create plugin API tokens, delete them, and change which domains each token is allowed to run on, without opening the dashboard.** This is aimed at multi-tenant setups. On a CRM platform where each customer runs on their own subdomain, a new customer's subdomain (`newcustomer.yourcrm.com`) can be added to an existing token as they sign up, and a departing customer's token can be deleted to revoke access. ## How it works ### 1\. Get an API key These endpoints authenticate with an API key from your account settings. Open Settings, go to API Tokens, select "Create API Token", and grant the token the permissions it needs. A token carries any of four permissions, read, create, update, and delete, and each endpoint checks the matching one. ### 2\. Set the request headers Every request carries these two headers: ```json { "accept": "application/json", "Authorization": "Bearer " } ``` ## Get a list of API tokens Retrieve a list of API tokens ### Endpoint `GET https://app.topol.io/api/api-tokens` ### Authentication - **BearerAuth** (http bearer) — Use: `Authorization: Bearer ` ### Responses #### 200 — API tokens fetched successfully Content-Type: `application/json` - `success` _boolean_ - `data` _object[]_ **required** - `id` _string_ **required** — API token ID - `name` _string_ **required** — API token name - `token` _string_ **required** — Public API token value - `domains` _string_ **required** — List of associated domains - `created_at` _string (date-time)_ **required** — Creation timestamp #### 401 — Unauthenticated. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 403 — Forbidden. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 404 — Not found. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 500 — Internal server error. Content-Type: `application/json` - `message` _string_ **required** — Error message ## Create a new API token Create a new API token ### Endpoint `POST https://app.topol.io/api/api-tokens` ### Authentication - **BearerAuth** (http bearer) — Use: `Authorization: Bearer ` ### Request body (required) Request body to create a new API token Content-Type: `application/json` - `name` _string_ **required** — API token name - `domains` _string_ **required** — Comma-separated list of domains ### Responses #### 200 — API token created successfully Content-Type: `application/json` - `data` _object_ **required** - `id` _string_ **required** — API token ID - `name` _string_ **required** — API token name - `token` _string_ **required** — Public API token value - `domains` _string_ **required** — List of associated domains - `created_at` _string (date-time)_ **required** — Creation timestamp - `settings` _object_ **required** — Settings associated with the API token #### 401 — Unauthenticated. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 403 — Forbidden. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 404 — Not found. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 422 — Validation error. Content-Type: `application/json` - `message` _string_ **required** — Main error message - `errors` _object_ **required** — Validation errors keyed by field name - `` _string[]_ #### 500 — Internal server error. Content-Type: `application/json` - `message` _string_ **required** — Error message ## Get an API token Get an existing API token ### Endpoint `GET https://app.topol.io/api/api-tokens/{apiTokenId}` ### Authentication - **BearerAuth** (http bearer) — Use: `Authorization: Bearer ` ### Parameters - `apiTokenId` (path) _string_ **required** — API token ID ### Responses #### 200 — API token retrieved successfully Content-Type: `application/json` - `data` _object_ **required** - `id` _string_ **required** — API token ID - `name` _string_ **required** — API token name - `token` _string_ **required** — Public API token value - `domains` _string_ **required** — List of associated domains - `created_at` _string (date-time)_ **required** — Creation timestamp - `settings` _object_ **required** — Settings associated with the API token #### 401 — Unauthenticated. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 403 — Forbidden. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 404 — Not found. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 500 — Internal server error. Content-Type: `application/json` - `message` _string_ **required** — Error message ## Delete an API token Delete an existing API token ### Endpoint `DELETE https://app.topol.io/api/api-tokens/{apiTokenId}` ### Authentication - **BearerAuth** (http bearer) — Use: `Authorization: Bearer ` ### Parameters - `apiTokenId` (path) _string_ **required** — API token ID ### Responses #### 200 — API token deleted successfully Content-Type: `application/json` - `success` _boolean_ **required** #### 401 — Unauthenticated. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 403 — Forbidden. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 404 — Not found. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 500 — Internal server error. Content-Type: `application/json` - `message` _string_ **required** — Error message ## Add domains to an API token Add domains to an existing API token ### Endpoint `POST https://app.topol.io/api/api-tokens/{apiTokenId}/add-domains` ### Authentication - **BearerAuth** (http bearer) — Use: `Authorization: Bearer ` ### Parameters - `apiTokenId` (path) _string_ **required** — API token ID ### Request body (required) Request body to add domains to an API token Content-Type: `application/json` - `domains` _string_ **required** — Comma-separated list of domains to add ### Responses #### 200 — API token deleted successfully Content-Type: `application/json` - `data` _object_ **required** - `id` _string_ **required** — API token ID - `name` _string_ **required** — API token name - `token` _string_ **required** — Public API token value - `domains` _string_ **required** — List of associated domains - `created_at` _string (date-time)_ **required** — Creation timestamp - `settings` _object_ **required** — Settings associated with the API token #### 401 — Unauthenticated. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 403 — Forbidden. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 404 — Not found. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 500 — Internal server error. Content-Type: `application/json` - `message` _string_ **required** — Error message ## Remove domains from an API token Remove domains from an existing API token ### Endpoint `POST https://app.topol.io/api/api-tokens/{apiTokenId}/delete-domains` ### Authentication - **BearerAuth** (http bearer) — Use: `Authorization: Bearer ` ### Parameters - `apiTokenId` (path) _string_ **required** — API token ID ### Request body (required) Request body to add domains to an API token Content-Type: `application/json` - `domains` _string_ **required** — Comma-separated list of domains to add ### Responses #### 200 — API token updated successfully Content-Type: `application/json` - `data` _object_ **required** - `id` _string_ **required** — API token ID - `name` _string_ **required** — API token name - `token` _string_ **required** — Public API token value - `domains` _string_ **required** — List of associated domains - `created_at` _string (date-time)_ **required** — Creation timestamp - `settings` _object_ **required** — Settings associated with the API token #### 401 — Unauthenticated. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 403 — Forbidden. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 404 — Not found. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 500 — Internal server error. Content-Type: `application/json` - `message` _string_ **required** — Error message ## Update storage settings for an API token Update storage settings for an existing API token ### Endpoint `PUT https://app.topol.io/api/api-tokens/{apiTokenId}/storage` ### Authentication - **BearerAuth** (http bearer) — Use: `Authorization: Bearer ` ### Parameters - `apiTokenId` (path) _string_ **required** — API token ID ### Request body (required) Request body to add domains to an API token Content-Type: `application/json` - `settings` _object | object | object_ **required** ### Responses #### 200 — API token storage updated successfully Content-Type: `application/json` - `data` _object_ **required** - `id` _string_ **required** — API token ID - `name` _string_ **required** — API token name - `token` _string_ **required** — Public API token value - `domains` _string_ **required** — List of associated domains - `created_at` _string (date-time)_ **required** — Creation timestamp - `settings` _object_ **required** — Settings associated with the API token #### 401 — Unauthenticated. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 403 — Forbidden. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 404 — Not found. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 422 — Validation error. Content-Type: `application/json` - `message` _string_ **required** — Main error message - `errors` _object_ **required** — Validation errors keyed by field name - `` _string[]_ #### 500 — Internal server error. Content-Type: `application/json` - `message` _string_ **required** — Error message ## Delete an API token storage settings Delete an existing API token storage settings ### Endpoint `DELETE https://app.topol.io/api/api-tokens/{apiTokenId}/storage` ### Authentication - **BearerAuth** (http bearer) — Use: `Authorization: Bearer ` ### Parameters - `apiTokenId` (path) _string_ **required** — API token ID ### Responses #### 200 — API token storage deleted successfully Content-Type: `application/json` - `data` _object_ **required** - `id` _string_ **required** — API token ID - `name` _string_ **required** — API token name - `token` _string_ **required** — Public API token value - `domains` _string_ **required** — List of associated domains - `created_at` _string (date-time)_ **required** — Creation timestamp - `settings` _object_ **required** — Settings associated with the API token #### 401 — Unauthenticated. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 403 — Forbidden. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 404 — Not found. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 500 — Internal server error. Content-Type: `application/json` - `message` _string_ **required** — Error message