Topol Documentation

Appearance

Adding tokens on demand ​

You can use our API to add a new plugin tokens, delete plugin tokens, add domains to existing plugin token and remove domains from existing plugin token.

Why? ​

Let's image you have a CRM application with multiple tenants. A new tenant joins your CRM and you want to restrict access of editor only for the newly created tenant subdomain.

You can use our API to add this new subdomain to the existing token as well as remove existing token when your tenant decides that he doesn't want to use the service anymore.

How to use it? ​

First, an API key is needed. To get started, you have two options: either an API key from your account settings or an API key from your Plugin API Token.

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 using the same API key that was used for the initialization of your Plugin, simply copy it from the Plugin Settings under "Show API key."

When working with the API, make sure to set the following headers:

Headers:

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

List tokens ​

To list your tokens you need to send a GET request to our API endpoint:

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

Response:

Successful response will look like this:

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 new token ​

WARNING

When creating a new token, the existing token will be overridden.

To add new token you need to send a POST request to our API endpoint:

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

Request:

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 comma.

Example:

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

Response:

If successful, our server will then return following 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 token ​

To remove a token you need to send a DELETE request to our API endpoint:

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

Response:

If successfully deleted, you will receive following response:

json
{
  "success": true
}

Add / remove domains of existing token ​

To add or remove domains from token you need to send a POST request to one of our 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

Request:

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 comma.

Example:

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

Response:

If successful, our server will then return following 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 message:

json
{
  "message": "Error message"
}