Authentication
Generate a personal API token and authenticate your requests to the smenso API.
How authentication works
The smenso API uses token-based authentication. Every API request must include a valid token in the Authorization header.
Tokens are user-scoped: they inherit the exact permissions and data visibility of the user who created them. If a user can see 5 out of 10 projects in the UI, the API will return only those 5 projects when using that user's token.
Creating an API token
To generate a personal API token:
- Open the Admin Center and log in.
- Navigate to the API Token section.
- Click Create API Token.
- Select the workspace the token should apply to.
- Set a validity period (expiration date).
- Assign a descriptive name (e.g., "CRM Integration - Production").
- Click Create.
A dialog displays the generated token details.
Important: Copy and store the token securely. It is displayed only once and cannot be retrieved after closing the dialog.
Using the token in requests
Include the token in the Authorization header of every request using the Basic scheme:
example
"headers": {
"Authorization": "Basic YOURTOKEN"
}Required headers summary
| Header | Value | When |
|---|---|---|
Authorization | Basic {your-api-token} | Every request |
Content-Type | application/json | POST/PUT requests (JSON API) |
Content-Type | application/xml | POST/PUT requests (XML API) |
Timezone | e.g., Europe/Berlin | Optional; overrides workspace default |
Error responses
| Scenario | HTTP status | Description |
|---|---|---|
| No token provided | 401 Unauthorized | The Authorization header is missing |
| Invalid or expired token | 401 Unauthorized | The token is not recognized or has expired |
| Insufficient permissions | 403 Forbidden | The token's user lacks the required role (e.g., non-admin trying to write) |
Token lifecycle and management
| Question | Answer |
|---|---|
| Can I have multiple tokens? | Yes. You can create multiple tokens, e.g., one per integration. |
| Can I revoke a token? | Yes. Tokens can be deleted in the Admin Center under API Token. |
| What happens when a token expires? | Requests return 401 Unauthorized. Generate a new token to restore access. |
| Can I extend a token's validity? | No. Create a new token and update your integration with the new value. |
| Is there a maximum validity period? | Yes. The maximum validity period is one year. |
Security best practices
- Never hardcode tokens in source code or commit them to version control.
- Use environment variables or a secrets manager to store tokens.
- Set short validity periods where possible and rotate tokens regularly.
- Create separate tokens for each integration to isolate permissions and simplify revocation.
- Revoke unused tokens promptly when an integration is decommissioned.
- Monitor API usage - if unexpected access patterns occur, revoke the affected token immediately.
Updated 16 days ago
What’s Next