Authentication

The Servicebay API uses API keys for authentication. Every request must include a valid key in the X-API-Key header.

Pro plan required

The API (and the developer portal itself) is a Pro feature. Requests from an organisation without an active Pro subscription return 403 — see Error Handling. Upgrade the organisation's plan in the Servicebay app to unlock access.

Building for other people's organisations?

API keys suit integrations you run against your own organisation. If users should connect their Servicebay organisation to your app with scoped, revocable permissions, use OAuth instead — or MCP for AI agents.

Getting an API key

Open developer.servicebay.io/login and sign in with your Servicebay credentials. If 2FA is enabled on your account, you'll be prompted for a TOTP code — see Two-Factor Authentication.

Pick an organisation

Each key is bound to a single organisation. Choose the org you want this key to act on from the dropdown.

Create the key

Click Create API Key, give it a descriptive name (e.g. production-intake-form), and copy the value.

The key is shown only once. Copy it somewhere safe before closing the dialog. If you lose it, revoke it and create a new one.

Using your API key

Include your key in the X-API-Key header on every request:

curl -X GET \
  'https://developer.servicebay.io/api/v1/organisations/{orgId}/customers' \
  -H 'X-API-Key: sk_live_your_api_key_here' \
  -H 'Content-Type: application/json'

Key format

Production keys begin with sk_live_ followed by 32 hexadecimal characters:

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The portion after the prefix is opaque — treat the entire string as a single secret.

Key scoping

Each API key is scoped to a single organisation. If you need to act on multiple organisations, create one key per organisation.

Revocation and expiry

A key is valid until it is revoked. Revoking a key from the developer portal takes effect immediately — subsequent requests return 401 with an error that the key has been revoked. A key may also carry an optional expiry; once past it, requests return 401 with an expired-key error. In both cases, create a new key to continue.

Security best practices

Never expose your API key in client-side code or public repositories. An exposed key gives the holder full read/write access to that organisation's data until you revoke it.

Store keys in environment variables, not in source files
Rotate keys regularly — delete old keys and create new ones periodically
Revoke compromised keys immediately from the developer portal
Use a separate key per integration so you can revoke one without breaking the others

Admin access required

Only users with the admin role in an organisation can manage API keys. Members can use existing keys but cannot create or revoke them.

Two-factor authentication for the portal

If your Servicebay account has 2FA enabled, the developer portal will require a 6-digit code from your authenticator app every time you sign in. This is enforced automatically — there is no opt-out.

For details on the TOTP enrolment and verification flow, see Two-Factor Authentication.

2FA only protects the dashboard. API requests using X-API-Key are not challenged because the API key itself is the credential.

Testing keys in the portal

The Developer Portal includes an API Playground for live requests. When you create a key in the current browser tab, the playground caches its value in session storage until you close the tab — a convenience for testing, not a substitute for secure storage in production.

Never paste production keys into public machines or shared browsers. Revoke any key that may have been exposed and rotate your integrations.

Authentication

On this page