API Keys: How the Default User Controls Data Access

What This Page Does

The Integrations page lets you create and manage API access keys — enabling programmatic access to Xenia data for custom integrations, dashboards, data extractions, or mobile apps.

Where to find it: Settings → Public Integrations

Creating an API Key

1. Go to Settings → Integrations
2. Click + Create API Key in the top right corner
3. The Create API Key modal opens

Client Key (required)
A human-readable identifier for this key — alphanumeric characters and hyphens only, minimum 5 characters. This becomes your x-client-key header value in every API request. Use something descriptive: powerbi-reporting, dashboard-integration, data-export.

Default User (required)
Select which Xenia user this API key will act as by default. See below for how this works.

4. Click Create API Key
5. Your client secret is shown once only — copy it immediately and store it securely. It cannot be retrieved after this screen closes.

Understanding the Default User Setting

The Default User is one of the most important settings on an API key — and the most commonly misunderstood.

What it does:
Every request made through this API key runs as the selected Default User. The key inherits that user's role, permissions, and location membership. Whatever that user can see and do in Xenia, the API key can see and do.

Two Additional Details Worth Knowing

1. You can override the Default User per request

You don't have to be locked to the Default User set at key-creation time. Pass an x-client-user header on any individual request to run that specific call as a different user instead. The specified user just needs to be a member of the workspace.

x-client-key: your-client-key
x-client-secret: your-client-secret
x-client-user: user-id-to-run-as

This gives you flexibility — set a sensible default at the key level, then override per request when you need different access for specific calls.

2. It's a real user account — not an abstract access level dial

The Default User is not a generic "access level" setting. You are selecting a real user account, and the actual permission checks in the API run against whatever role and permissions that user account actually has in Xenia.

Picking "Admin" as the Default User doesn't grant admin-level access in the abstract — it runs every request as that specific Admin user, with all of their actual configured permissions and location memberships applied.

Recommended Setup

For integrations that need full workspace data visibility (Power BI, data exports, analytics dashboards):

1. Create a dedicated integration user — e.g. api-integration@yourcompany.com — rather than using a personal account
2. Assign it an Admin or Owner role with membership at all relevant locations
3. Select this dedicated user as the Default User on the API key

Using a dedicated user means the integration doesn't break when a team member leaves, and you have clear visibility into what the API key can access.

Your Two Credentials

After creating the key you have two values — both required as headers on every API request:

Frequently Asked Questions

Q: What happens if I select a user with limited location access as the Default User?
The API key will only be able to access data from the locations that user is a member of. If you need full workspace visibility, select a user with Admin access and full location membership.

Q: Can I change the Default User after the key is created?
No — the Default User is set at key creation and cannot be changed. If you need a different Default User, create a new key and deactivate the old one.

Q: What if I want some API calls to use Admin access and others to use limited access?
Use the x-client-user header to override the Default User on specific requests. Set a sensible default at the key level and pass a different user ID per request when needed.

Q: Is the client secret stored anywhere I can retrieve it later?
No. The client secret is displayed once at key creation. If it's lost, you must create a new key. Treat it like a password — store it in a secure secrets manager immediately.

Q: Can I have multiple API keys for different integrations?
Yes — there's no enforced limit. Creating separate keys for separate integrations is recommended so you can deactivate one without affecting others.

For setup assistance contact support@xenia.team