Skip to content
Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// integration

Authentication

Applies to

Product: Cloud · Server · Audience: Developer / Integrator

Shared vs. personal credentials, handling tokens and how basebox passes a user's identity on to the connected system. The rule in one sentence: your server owns no user credentials – it passes them through.

The two models

Model Where the credentials come from When appropriate
Personal credentials basebox sets the Authorization header per request with the token of the asking user Always when the target system knows permissions per person – the norm
Service account A machine key from a Kubernetes secret in your environment Only for content all users may see anyway (public wiki, general manual)

A connector can combine both – say a service account for an anonymous index and personal tokens for access to content. The access model belongs in the tool description and in your documentation so administrators know it when enabling.

How personal credentials reach you

  1. The user enters their token once in basebox (in the chat via "+" or under Settings → Connectors) and clicks Test connection.
  2. basebox stores it write-only in the user settings. No administrator sees it.
  3. On every tool call, AISRV loads the token fresh by user_id and produces the header from it – Bearer or HTTP Basic, depending on the connector configuration.
  4. POST /mcp to your server carries this header. You pass it on unchanged to the target system.

There is no step in which your server accepts a token in order to keep it. A login tool ("sign me in") is a design error.

What you do with the header

  • Pass it on, exactly as received, with every call to the target system.
  • Do not store – not in the process beyond the request, not on disk, not in a cache key.
  • Do not log – not even truncated, not even as a hash. Credentials never appear in production logs; during targeted diagnostic runs at most at level DEBUG.
  • Do not transform – no exchange for another token, no enrichment. If the target system needs a different header name (X-Auth-Token, PRIVATE-TOKEN), carry the value over, but without enriching or extending it.
  • If the header is missing, respond with a clear tool error ("No credentials stored – please set up the connector in basebox"), not with a fallback to a service account.

Which token users should enter

Require a dedicated, revocable access token of the target system – never the login password. Examples: permanent tokens in YouTrack, app passwords or tokens in wikis, OAuth tokens with limited scope. Describe in your documentation how users generate it; for YouTrack such a guide exists under Create a YouTrack token.

Recommend the minimal scope to users: read-only if only reading is done; limited to the projects or areas they need.

Using service accounts properly

  • Provide as a Kubernetes secret and load it into your container via valueFrom.secretKeyRef – never in clear text in Helm values or in the image.
  • A dedicated account with minimal, read-only rights; no real person's account.
  • Plan for rotation: the secret can be swapped without rebuilding the connector.
  • Make clear in the tool description that results are not user-specific.

Mapping target system errors

Target system responds Your tool result
401 Unauthorized "Credentials invalid or expired – renew token in basebox"
403 Forbidden "No access to this resource" – no circumvention, no fallback
404 Not Found "Not found" – the same the user would see directly
429 Too Many Requests "Rate limit reached – try again later"
5xx "Target system unreachable" with brief cause

These messages come back as data; the model explains them to the user. They must not contain details beyond what the target system discloses.

Test connection

Administrators and users click Test connection in basebox. For that to be meaningful, your server should be able to perform a cheap, read-only call against the target system that confirms authentication with the passed credentials – for example fetching the user's own profile.

Checklist

  • No storing, no logging, no caching of credentials
  • Header passed on unchanged; Bearer and Basic supported as far as the target system knows them
  • Missing header → clear error, no fallback
  • 401/403 of the target system → returned as result, never circumvented
  • Service account only from Kubernetes secret, read-only, only for generally accessible content
  • Documentation of which token users generate and how

Next: Read access · Connector authentication (admin view) · Authorization flow