smoxy

English

Deutsch

English

Deutsch

Appearance

API Tokens ​

API tokens are personal access tokens for the smoxy API. They authenticate your requests so you can automate tasks - configuring zones, managing settings, or retrieving data - without logging in through the dashboard.

Treat a token like a password: anyone who has it can act on your behalf. Tokens are managed from your Account area under API tokens.

WARNING

Keep tokens secret. A token grants the same access as your account within its scope. Never commit a token to source control, paste it into shared documents, or expose it in client-side code.

Creating a Token ​

Open Account → API tokens and create a new token. You provide:

FieldDescription
NameA label to identify the token later, e.g. CI/CD pipeline. It has no effect on access - it only helps you tell tokens apart.
ExpirationAn optional expiry date. Leave it empty for a token that never expires.
Organization accessEither All organizations (every organization you are a member of) or Specific organizations (only the ones you add).
The Create API token form: name, optional expiration and organization access.The Create API token form: name, optional expiration and organization access.
The Create API token form: name, optional expiration and organization access.

Choosing Specific organizations reveals a search box for adding the organizations the token may access.

Restricting a token to specific organizations: search for and add each one.Restricting a token to specific organizations: search for and add each one.
Restricting a token to specific organizations: search for and add each one.

WARNING

Copy the token immediately. The token value is shown only once, right after creation. Once the dialog closes it cannot be retrieved again - if you lose it, you have to create a new one.

Managing Tokens ​

The API tokens list shows every token you have created, along with:

  • Created - when the token was generated.
  • Last used - when the token last authenticated a request, or Never used if it has not been used yet.
  • Expires - the expiry date, or Never expires if none was set.

Revoking a Token ​

You can revoke a token at any time. A revoked token stops working immediately, and any integration using it will be denied access on its next request. Revoke a token as soon as it is no longer needed or if you suspect it has been exposed.

Legacy API Tokens ​

Some accounts may still have legacy API tokens - an older token type that is deprecated and less secure than personal access tokens.

If you have legacy tokens, rotate them to personal access tokens:

  1. Create a new personal access token with the appropriate organization access.
  2. Update your integrations to use the new token.
  3. Delete the legacy token once nothing depends on it.

WARNING

Deleting a legacy token takes effect immediately. Any integration still using that token will stop working as soon as it is deleted. Make sure every integration has been switched over first.

Using the Token ​

The smoxy public API is available at https://api.smoxy.eu. Authenticate each request by sending your token in the X-API-TOKEN HTTP header:

bash
curl -H "X-API-TOKEN: <token>" https://api.smoxy.eu/api/zones

For the full list of endpoints, request parameters, and response formats, see the API Reference.

Best Practices ​

  • Store tokens securely. Keep them in a secrets manager or environment variables, never in source control or plain text.
  • Scope to specific organizations. When a token only needs access to one organization, restrict it to that organization instead of granting All organizations.
  • Set an expiration. Expiring tokens limit how long a leaked token stays useful. Use short lifetimes where you can rotate them automatically.
  • Rotate and revoke regularly. Replace tokens periodically and revoke any that are unused, no longer needed, or possibly exposed.