Skip to content

Adding Tokens on Demand

Topol lets you manage your plugin API tokens dynamically using an API. This means you can create new tokens, delete old ones, and update which domains are allowed to use each token — all without logging into the dashboard every time.

Why Would You Use This?

Imagine you run a CRM platform with many customers (tenants). When a new customer joins, you want to give them access to the editor—but only on their specific subdomain (like newcustomer.yourcrm.com). Using this API, you can add that subdomain to your existing token easily.

Or, if a customer leaves, you can remove their access by deleting their token.

How Does It Work?

1. Get an API Key

You need an API key to call these token management APIs. You can get it either from your account settings or from your existing Plugin API Token settings.

When using an API key from your account settings, you can set various permissions. Go to Settings, then navigate to API Tokens. From there, select "Create API Token" and specify the permissions you wish to grant to this token.

If you prefer to use the same existing Plugin API token that was used to initialize your Plugin, simply copy it from the Plugin Settings under "Show API key".

2. Set API Request Headers

When making requests, include these headers:

json
{
  "accept": "application/json",
  "Authorization": "Bearer <api-key>"
}

Available API Endpoints

List All Tokens

Send a GET request to this endpoint to see all tokens, their domains, and creation dates.

  • URL: https://app.topol.io/api/api-tokens
  • Method: GET

Response:

json
{
  "data": [
    {
      "id": "token1-uuid",
      "name": "token1-name",
      "token": "token1",
      "domains": "example.com,example2.com",
      "created_at": "2023-01-01T00:00:00.000000Z"
    },
    {
      "id": "token2-uuid",
      "name": "token2-name",
      "token": "token2",
      "domains": "example.com,example2.com",
      "created_at": "2023-01-02T00:00:00.000000Z"
    }
  ]
}

Add a New Token

WARNING

Creating a new token will override the existing one!

Send a POST request to the same URL with the token name and allowed domains (comma-separated).

  • URL: https://app.topol.io/api/api-tokens
  • Method: POST

Request:

json
{
  "name": "new-token-name",
  "domains": "example.com,example2.com"
}

Both name and domains are required:

  • name can have maximum of 255 characters.
  • domains can have maximum of 5000 characters and can contain multiple valid domains (each with maximum of 253 characters) separated by a comma.

Response:

json
{
  "data": {
    "id": "new-token-uuid",
    "name": "new-token-name",
    "token": "new-token",
    "domains": "example.com,example2.com",
    "created_at": "2023-01-01T00:00:00.000000Z"
  }
}

Delete a Token

Send a DELETE request to this endpoint to remove a token.

  • URL: https://app.topol.io/api/api-tokens/{apiTokenId}
  • Method: DELETE

Response:

If successfully deleted, you will receive following response:

json
{
  "success": true
}

Add Domains to a Token or Remove Domains from a Token

To add domains to a token or remove domains from a token, send a POST request to one of these API endpoints:

Add domains:

  • URL: https://app.topol.io/api/api-tokens/{apiTokenId}/add-domains
  • Method: POST

Remove domains:

  • URL: https://app.topol.io/api/api-tokens/{apiTokenId}/delete-domains
  • Method: POST

Both share the same request, response and error response.

Request:

json
{
  "domains": "example.com"
}

The domains is required:

  • domains can have maximum of 5000 characters and can contain multiple valid domains (each with maximum of 253 characters) separated by a comma.

Response:

json
{
  "data": {
    "id": "token-uuid",
    "name": "token-name",
    "token": "token",
    "domains": "example.com",
    "created_at": "2023-01-01T00:00:00.000000Z"
  }
}

Error Response:

If a request is not successful, you will get a response with appropriate error code and a message explaining the error:

json
{
  "message": "Error message"
}