API Token Management

Create, use, revoke, and refresh API tokens for programmatic access to your pipelines.

Overview

API tokens provide programmatic access to MechaMental's endpoints. Use them to call your deployed pipelines from backend services, scripts, CI/CD workflows, and client applications.

Creating a Token

Open the Tokens Tab

Navigate to your app and open the Tokens tab.

Create a New Token

Click the Create Token button
Fill in the required fields:
- Name -- a descriptive label (e.g., "CI/CD Pipeline", "Mobile App Backend")
- Expiration -- set an expiration date for the token
Click Create

Copy the Token Value

The token value is displayed only once immediately after creation. Copy it and store it securely (e.g., in a secrets manager or environment variable).

Token Security

The full token value is shown only at creation time. If you lose it, you will need to create a new token. Never commit tokens to source control or share them in plain text.

Using Tokens in API Calls

Include the token in the Authorization header as a Bearer token:

curl -X POST https://api.mechamental.com/v1/trigger/chat \
  -H "Authorization: Bearer mm_tok_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, how can I reset my password?"}'

For SSE streaming endpoints, the same authentication applies but the response is a stream of server-sent events:

curl -N -X POST https://api.mechamental.com/v1/trigger/chat \
  -H "Authorization: Bearer mm_tok_abc123..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"message": "Summarize the Q3 report"}'

Revoking a Token

When a token is no longer needed or has been compromised:

Navigate to the app's Tokens tab
Find the token in the list
Click the Revoke action
Confirm revocation -- the token stops working immediately

Revocation is instant and irreversible. Any requests using the revoked token will receive a 401 Unauthorized response.

Refreshing a Token

To extend a token's lifetime before it expires:

Find the token in the Tokens tab
Click the Refresh action
The token's expiration is extended without changing the token value

This avoids the need to create a new token and update all integrations that reference it.

Rotation Strategy

For production integrations, implement token rotation: create a new token before the old one expires, update your integration to use the new token, then revoke the old one. This ensures zero downtime during rotation.

Best Practices

Set expiration dates -- avoid creating tokens that never expire. Set a reasonable expiration and use the refresh mechanism to extend when needed.
Use descriptive names -- name tokens after their use case so you can identify and audit them later.
Revoke unused tokens -- regularly audit your token list and revoke any that are no longer in use.
One token per integration -- create separate tokens for each service or integration so you can revoke individually without affecting other systems.

On this page