November 2026 release is live Read More

Service Account

At a glance

  • What it is. A login for a program, not a person. Power BI, a script or an AI agent uses it to read Mavvrik data, or, with a write role, to change it. Each account has its own name, role, team and keys that expire.

  • Why it matters. No shared logins, and automation keeps working when people leave. Each tool sees only the data of its teams.

  • Main risk. Write roles (Finance Manager, Operations Manager) can change budgets, forecasts, cost allocations and settings for the whole tenant. Rule: use Member for reporting and read-only use. Use Finance Manager only for anything that changes budgets or allocations, and give its key a short expiry.

  • Who owns it. Owners and Editors create and manage service accounts.

A service account is a machine user inside your Mavvrik tenant. Use it to let Power BI, a script or an AI agent read Mavvrik data (or, with a write role, change it) without sharing a person's login or the tenant-wide Admin API key. Roles decide what the account can do, and teams decide which cost data it can see.

Availability: Service Accounts is turned on per tenant. If you do not see Admin › Users & Access › Service Accounts, ask Mavvrik Support to turn on Service Accounts for your tenant.

Why use a service account

  • Limited data. The account only sees the cost data of the teams you link to it.

  • Its own identity. Each account has a name, roles and a list of keys, so you can see who uses what and when.

  • Safe rotation. Every key has an expiry date and can be switched off or revoked on its own, without breaking the other keys.

Example scenarios

These everyday examples show how teams use a service account. The names are made up. A key works like a password for a program, and every key has an expiry date. To revoke a key means to remove it for good, so it can never be used again. The technical details are in the Developer guide at the bottom.

1. A monthly cost report that updates by itself

The need. The finance team shows monthly cloud costs in a reporting tool such as Power BI. The report used to sign in with one analyst's own login, so it stopped working whenever that person changed jobs or left.

How it is set up.

  • Account name: powerbi-finance-report

  • Access level: Member (reads data and can create bookmarks, but cannot create dashboards or reports)

  • Team: Finance

  • Key: expires after 90 days

What they get. The report refreshes on its own and shows only Finance team costs. When the analyst leaves, nothing breaks. Before the key expires, the team adds a new key, points the report at it and revokes the old one (see Rotate a key without downtime).

2. Each team sees its own spending, and only its own

The need. The Platform team wants a small program that posts its daily cloud spend to the team's chat channel. It must not be able to see what other teams spend.

How it is set up.

  • Account name: platform-nightly-spend

  • Access level: Member

  • Team: Platform

  • Key: expires after 90 days

What they get. The program sees Platform costs only. If it asks for another team's data, it gets nothing back. Other teams set up their own accounts the same way.

3. An AI assistant answers cost questions

The need. The Operations team lets an AI assistant answer questions such as "What did our team spend on compute last week?"

How it is set up.

  • Account name: ai-agent-cost-questions

  • Access level: Member

  • Team: Operations

  • Key: expires after 90 days

What they get. The assistant can read Operations costs and nothing else. It cannot change anything unless Mavvrik Support turns that on for your company.

4. A software release stops when the budget is used up

The need. Before a new version of the software goes live, an automatic check looks at the team's budget. If the budget is already used up, the release stops.

How it is set up.

  • Account name: ci-budget-check

  • Access level: Member

  • Team: the team that owns the budget

  • Key: expires after 30 days, kept in the release tool's secure storage

What they get. The check sees only the budgets shared with its team. Because the key lasts only 30 days, the team adds a new one before the old key expires.

5. New projects get a budget automatically

The need. The FinOps team wants a budget to be created automatically each time a new project starts, so nobody has to do it by hand.

How it is set up.

  • Account name: finops-budget-automation

  • Access level: Finance Manager (can create and change budgets)

  • Team: FinOps

  • Key: expires after 30 days

What they get. Every new project gets a budget without manual work. Because this account can change data, it uses a short key expiry.

6. A contractor key leaks

What happened. A contractor's program uses a key that was accidentally posted in a public place.

What to do. Open the account and switch the key off or revoke it. It stops working within about a minute, and the account's other keys keep working. If you cannot tell which key leaked, set the whole account to inactive, which stops all of its keys. Then create a new key for the contractor. See Stop a leaked key.

7. An employee leaves and the automations keep running

What happened. The person who owned a reporting program leaves the company, and their user is deactivated.

What it means. Nothing breaks, because the program uses a service account and not that person's login. From time to time, check the Last used dates and revoke keys that nobody uses.

Before you begin

  • You need to be an Owner or Editor in the tenant.

  • If the account should see cost data, create or pick a team first.

  • Have your tenant ID and API addresses ready. They are on Admin › Users & Access › API.

Roles

A service account needs at least one role. It can do what a person with the same role can do. The roles you can give are:

Role

What the account can do

Member

Read data it is allowed to see. Create bookmarks. It cannot create dashboards or reports.

Executive

Same as Member, for executive views.

Finance Manager

Everything a Member can do, plus create and change dashboards, reports, budgets, forecasts, cost allocations, alerts and settings.

Operations Manager

Same write access as Finance Manager.

The Editor and Owner roles cannot be given to a service account. A service account also cannot manage the tenant: it cannot create or change teams, users, other service accounts or the Admin API key, and it cannot log in to the Mavvrik web app.

Writes apply to the whole tenant. The team limit only restricts what the account can read. Give the narrowest role that does the job (see At a glance at the top).

Teams and data access

Link one or more teams to the account. Every cost query the account makes is limited to the data of those teams, and a request it makes for data outside its teams returns nothing.

  • Teams are optional, but an account without a team sees no cost data.

  • Budgets shared with a specific team are visible only to accounts linked to that team. Budgets that are not shared with any team are visible to all.

  • Alerts, users, teams, cloud and AI accounts, Kubernetes and datacenter inventory follow the account's roles only. They are not limited by team, the same as for people.

  • You can link an account from the account form or from the Service Accounts field in the team form.

  • A team that still has a service account linked cannot be deleted. Unlink the account first.

Create a service account

  1. Go to Admin › Users & Access › Service Accounts.

    image-20261111-141814.png
  2. Click Create Service Account.

  3. Enter a Name (required) and an optional Description. HTML tags in the name or description are removed when you save.

  4. Choose one or more Roles.

  5. Choose the Teams the account may read data from.

  6. Choose when the first key expires under Credential expires in: 30, 90, 180 or 365 days, or Custom (1 to 365 days).

  7. Click Save.

    image-20261111-141907.png
  8. Copy the key shown in the Token created window and store it in your secret manager.

    image-20261111-141938.png

The key is shown only once. Mavvrik stores only a fingerprint of it and cannot show it again. If you lose it, add a new key and revoke the old one.

Change an account

  1. In the list, click the pencil icon on the account.

  2. Change the name, description, roles or teams. Use the Active toggle to disable or re-enable the account.

  3. Click Save.

Changes to roles, teams and the Active toggle take effect within about a minute, and the existing keys keep working with the new access. You do not need to create new keys. A disabled account stops all of its keys. Re-enabling it brings them back. The account must always keep at least one role.

Rotate a key without downtime

  1. Open the account and add a new credential (or client secret). Copy it.

  2. Update your tool, script or Power BI data source to use the new key.

  3. Check that the old key's Last used date has not moved. Wait at least a day before you decide. Last used is recorded at most once an hour per key, so a quick check can look as if the key stopped when it is still in use.

  4. Switch the old key off. If something still depends on it, switch it back on while you fix the tool.

  5. When everything works, revoke the old key.

Stop a leaked key

  • One key: switch it off or revoke it. The account's other keys keep working.

  • Everything on an account: set the account to inactive or delete it. All of its keys stop.

Access stops within about a minute, usually much faster. A deleted account cannot be restored.

Expiry reminders

Owners and Editors receive one email a week that lists the keys expiring within 30 days. Once any key has 7 days or less left, the email is sent every day. The email names the account, the key type, the key name and the expiry date. Keys that are switched off are not listed. If an email cannot be sent, it is tried again the next day. Reminders are sent by email only. In the key list, the Status column shows Expiring soon for keys that are close to expiry. An expired key stops working.

The Admin API key

The tenant-wide key on Admin › Users & Access › API keeps working as before and is now labelled Admin API Key. It sees all tenant data and has no identity, so prefer a service account for tools that need only part of the data.

Developer guide

Open the section below if you set up the tools that call Mavvrik. It covers keys, API calls, limits and troubleshooting.

Developer guide: keys, API calls, limits and troubleshooting

Keys

Each account can have up to 10 credentials and up to 10 OAuth client secrets.

Item

Credential

OAuth client secret

Looks like

mvk_sa_<id>.<secret>

mvk_cs_<id>.<secret>

Used for

Sent directly in the x-api-key header on GraphQL, REST and MCP. Best for Power BI and scripts.

Exchanged for a one-hour access token. Best for tools that sign in with OAuth client credentials.

Where to find it

Account drawer, Credentials tab

Account drawer, OAuth tab

Open an account by clicking its name in the list. For each key you can see its name, the last characters of the secret, who created it, when it was created, when it expires, its status and when it was last used.

  • Expiry is fixed. The expiry date is set when the key is added and cannot be changed. To extend access, add a new key before the old one expires.

  • Rename. The pencil icon lets you rename a key (up to 100 characters). Renaming does not change the secret.

  • Switch off or on. Use the Active toggle to pause a key. You can switch it back on later.

  • Revoke. The trash icon permanently removes a key. Other keys on the account keep working.

  • Last used. Shows the date the key last made a request, or Never.

Call the API with a service account

Replace <app-domain> and <tenant-id> with the values on Admin › Users & Access › API.

REST

Bash
curl "https://api.<app-domain>/<tenant-id>/budget" \
  -H "x-api-key: mvk_sa_..."

GraphQL

GraphQL needs the tenant header as well as the key.

Bash
curl -X POST "https://graphql.<app-domain>/" \
  -H "x-api-key: mvk_sa_..." \
  -H "tenant: <tenant-id>" \
  -H "content-type: application/json" \
  -d '{"query":"{ __typename }"}'

OAuth client credentials

  1. Open the account, go to the OAuth tab and note the Token URL and Client ID (the format is <tenant-id>.<account-id>). Add a client secret and copy it.

  2. Request an access token (see the command below). The response contains an access_token that starts with mvk_at_ and is valid for 3600 seconds (one hour), or until its client secret expires if that comes first. Close to the secret's expiry, a token can therefore last less than an hour.

  3. Send the token as a Bearer token on REST or GraphQL calls. GraphQL also needs the tenant header.

Bash
curl -X POST "https://oauth.<app-domain>/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<client-id>&client_secret=mvk_cs_..."

curl "https://api.<app-domain>/<tenant-id>/budget" \
  -H "Authorization: Bearer mvk_at_..."

Request a new token before the current one expires. A client secret (mvk_cs_) is only used at the token address. The API itself does not accept it.

MCP connectors

AI agents and MCP connectors can use a service account at https://mcp.<app-domain>/mcp. Send either the credential with the tenant header, or the access token as a Bearer token. The connector only sees the tenant of the account, limited to the account's teams and roles. A service account cannot switch to another tenant. Writes through MCP also need to be enabled for your tenant by Mavvrik Support.

Interactive MCP clients such as Claude Desktop or ChatGPT cannot sign in as a service account yet. Use a credential or access token instead.

Limits

Item

Limit

Credentials per account

10

OAuth client secrets per account

10

Key expiry

1 to 365 days, fixed when the key is added

Key name

100 characters

OAuth access token lifetime

1 hour, or until its client secret expires if that comes first

Time for a change to take effect (revoke, switch off, role or team change, delete)

Up to about 1 minute

Usage quota

Requests from service accounts count toward your tenant's usage quota (the MCP pool). Once the limit is reached, requests are refused.

Troubleshooting

You see

Likely reason and fix

REST returns 401

The key is wrong, switched off, revoked or expired, or the account is disabled. Check the key in the account drawer and add a new one if needed.

GraphQL returns HTTP 400 with Context creation failed: 401

Same as above. GraphQL reports an invalid key this way. Also check that you sent the tenant header.

GraphQL returns Context creation failed: 403

The account has no team linked. Link a team.

A request returns 403

The account's role does not allow that action. For example, a Member cannot create budgets, dashboards or reports. Use a role that allows it. Cost queries from an account with no team also return 403 (see the row above).

A cost query returns no rows

The data you asked for belongs to a team that is not linked to the account.

Calls that worked before are now refused

Your tenant's usage quota (the MCP pool) may be used up. Service account requests count toward it. Ask Mavvrik Support to check the quota.

Request failed when adding a key

The account may already have 10 keys of that type. Revoke one you no longer need.

Delete failed on a team

A service account is still linked to the team. Unlink it first.

The token request is refused

The Client ID or the client secret is wrong, or the secret is switched off, revoked or expired. Check both on the OAuth tab.

You cannot find the Service Accounts page

The feature is not enabled for your tenant, or your role is not Owner or Editor. Contact Mavvrik Support.

  • Teams: create a team that limits which cost data a service account can read.

  • Users & Access: manage people and their roles.