API Tokens

API tokens give your external systems and scripts secure, scoped access to the Mirox platform without sharing your login credentials. You create them in your profile, give each one only the permissions it needs, and revoke or rotate any of them at any time.

Overview

Unlike your username and password, an API token:

• Carries a specific permission group that limits what it can reach
• Has a configurable expiration date (default one year, maximum five years)
• Can be rotated to a new secret or revoked individually, without touching your account or your other tokens
• Records its own usage history (last-used time, source IP, location, browser, and operating system) so you can see how each integration is behaving

You can hold up to 64 tokens at a time.

Creating API Tokens

API tokens can be created through the Mirox web interface:

1. Log in to your Mirox account
2. Open the Profile menu (top right) and choose Profile
3. Select the "API Tokens" tab
4. Click "Create New Token"
5. Configure token settings:
   • Name (descriptive label for the token)
   • Expiration date (defaults to 1 year if not specified, maximum 5 years)
   • Permission scope (specific resources and actions the token can access)
6. Click "Generate Token"

Open in Mirox: Profile ▸ API Tokens — manage your tokens from the Profile menu ▸ Profile, then the "API Tokens" tab.

Token Security Best Practices

When working with API tokens:

1. Store Securely - Treat tokens like passwords; never hardcode them in applications
2. Use Environment Variables - Store tokens in environment variables or secure credential stores
3. Limit Scope - Create tokens with the minimum permissions needed for the integration
4. Set Appropriate Expirations - Use shorter expiration periods for temporary integrations
5. Plan for Rotation - Set calendar reminders before token expiration to ensure service continuity
6. Rotate Regularly - Use the built-in Rotate action to roll a token's secret periodically before its expiration, especially for production systems
7. Revoke Unused - Immediately revoke tokens that are no longer needed
8. Monitor Usage - Regularly audit token activity through the Mirox interface

Using API Tokens

API tokens are used in HTTP requests as a Bearer token in the Authorization header:

Authorization: Bearer your-api-token

The following examples require a token in the Full Access permission group.

Example HTTP Request

GET /api/v1/park HTTP/1.1
Host: service.mirox.io
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Curl Example

curl -X GET \
  https://service.mirox.io/api/v1/park \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json'

Token Permissions

API tokens are subject to the API-Token Permission Layer of the Mirox platform. Key points about token permissions:

• Tokens inherit permissions from the user who created them (never more)
• Permissions can be further restricted on a feature basis
• Tokens operate within the same hierarchical permission model as user accounts
• All platform security controls apply to token-based access

For detailed information on how API tokens fit within the overall permission architecture, see the Permission System documentation.

Permission Groups

When you create a token, you choose one of three permission groups that scope what it can reach:

• Full Access — grants the token the same permissions as your user account, within your scope. Any service using it can act on your behalf across the platform, so only choose this when an integration genuinely needs broad access.
• Reporting — restricts the token to reporting features: generating reports and exporting data.
• Timeseries Database — restricts the token to time-series query endpoints, for pulling measurement data programmatically (for example with MiroxQL).

Pick the narrowest group that covers your integration. A Reporting or Timeseries Database token cannot reach anything outside its scope, which limits the blast radius if it is ever leaked.

Token Lifecycle Management

Monitoring Token Usage

Track API token activity through:

1. The "API Tokens" section in your profile
2. Audit logs that show when and how each token was used

Rotating Tokens

Rotation replaces a token's secret without changing its name, permission group, or place in your token list. This lets you roll a key on a schedule, or react to a suspected leak, while keeping the same token entry in your integrations' configuration.

To rotate a token:

1. Navigate to the "API Tokens" section in your profile
2. Find the token in the list and choose "Rotate"
3. Copy the new secret immediately — it is shown only once
4. Update the secret in the integration that uses it

Rotation issues a new secret, resets the expiration window, and clears the token's recorded usage history. The old secret stops working immediately, so update your integrations as part of the rotation.

Revoking Tokens

To revoke a token:

1. Navigate to the "API Tokens" section in your profile
2. Find the token in the list
3. Click "Revoke"
4. Confirm the action

Revocation takes effect immediately, and any subsequent requests using the token will fail.

Usage Limitations

API tokens are subject to the same rate limits as normal user accounts. For details on these limitations, see the Rate Limiting section in the Authentication Concepts documentation.

Troubleshooting

Common token issues and solutions:

Code Examples

For working code that uses an API token end to end, see:

• External Report Generator — a Python script that authenticates with a token and pulls a metrics export
• MiroxQL — the query language for pulling time-series data with a Timeseries Database token

Related Features

• API Overview — the entry point to the Mirox REST API and its live documentation
• Permission System — how token permission groups fit the platform's role model
• Authentication — sessions, two-factor login, and the rate limits that also apply to tokens
• MiroxQL — query time-series data programmatically with a Timeseries Database token
• Metrics Export API — export measurement data and reports with a Reporting token