Authentication

How authentication works on the go~mus API - bearer tokens, context awareness, foreign_id pattern, best practices.

go~mus authenticates API calls via bearer tokens. Standard OAuth 2.0 pattern. Special: tokens are context-aware. The response varies depending on the token.

Header format

On every request:

Authorization: Bearer <token>

Example:

curl -H "Authorization: Bearer abc123def456..." \
  https://demo.gomus.de/api/v4/whoami

Token types

Three classes of tokens, identical structure, different authorization:

  • Public: read-only, auth not required for most endpoints. When auth is used, additional fields or filters may become available.
  • User: for backend users. Sees everything within assigned rights and museums.
  • Reseller: for distribution partners. Reads only tickets/events cleared for them. Writes orders and reservations. Rate-limited.

Which token type fits your use case is clarified by go~mus support during setup.

Context awareness in action

Same endpoint, three tokens, three answers:

# Public call (no token)
curl https://demo.gomus.de/api/v4/tickets
# → public list, possibly restricted

# With user token
curl -H "Authorization: Bearer USER_TOKEN" \
  https://demo.gomus.de/api/v4/tickets
# → full backend inventory

# With reseller A token
curl -H "Authorization: Bearer RESELLER_A_TOKEN" \
  https://demo.gomus.de/api/v4/tickets
# → only tickets cleared for reseller A

Implication for your implementation: do not hard-code assumptions about fields or counts. Log unknown fields rather than crash.

Token test

Before any integration, validate the token with whoami:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://demo.gomus.de/api/v4/whoami

Response:

{
  "access": "user",
  "museums": []
}

access is public, user or reseller. museums: [] means all museums on the instance are reachable. Specific IDs narrow the scope.

foreign_id pattern

If your system has its own customer ID, attach it as foreign_id. On the next update reference via foreign_id instead of the go~mus ID:

# Initial create with foreign_id
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://demo.gomus.de/api/v4/customers \
  -d '{
    "name": "Max",
    "surname": "Mustermann",
    "email": "max@example.com",
    "foreign_id": "crm-customer-9f8a7b6c5d4e3f21"
  }'

# Update via foreign_id lookup
curl -X PUT -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://demo.gomus.de/api/v4/customers \
  -d '{
    "foreign_id": "crm-customer-9f8a7b6c5d4e3f21",
    "phone": "+49 30 1234567"
  }'

Benefit: no mapping table on your side. Recommendation: 16+ random characters or UUID for collision-free IDs.

Best practices

Never expose tokens client-side. No browser JS, no mobile app bundle. Hold tokens on your server and proxy API calls.

Do not share tokens. One token per partner. If a token gets compromised, the blast radius is contained.

Rotate tokens. On personnel changes or suspected leaks. Via go~mus support or backend, depending on setup.

Respect rate limits. Reseller tokens have limits. When exceeded you get 429. Implement exponential backoff.

Cache yes, live traffic no. Cache master data daily. Availability live. Direct live traffic without caching is a no-go for production.

Logging. Log every API call with timestamp, endpoint, status, response time. You will need it for support tickets.

Security

If you suspect a token leak: revoke immediately. Email support@giantmonkey.de with subject "Security".

For API vulnerabilities, please disclose responsibly. See security.txt.

What next

  • Quickstart: first call in five minutes.
  • Concepts: more vocabulary you will need.
  • API reference: full spec on your instance at https://<instance>.gomus.<tld>/api-docs.