Usage docs

Maatriks lets your AI agent use the services your company connects without giving the agent the company's API keys. Your administrator adds a Connection for each service, decides which people may use it and reviews a record of every call. You sign in with your Microsoft work account; your agent then calls each service's own API through Maatriks.

Your organization must be set up before you can use it. Ask your administrator for the Microsoft work account to use. The service address is maatriks.ai.

If you are an employee, begin with Connect your agent. If you administer your organization, begin with Set up your organization. Limits and retention and Troubleshooting apply to both.

Understand the main terms

A Connection is a named company account with one service, such as OpenAI or ElevenLabs, or with another HTTPS API your administrator describes. Its API key stays with Maatriks; employees and their agents never receive it.

Preconfigured services are OpenAI, Anthropic, Gemini, ElevenLabs, Jutusta and HeyGen. Maatriks already knows their address, where their key goes, their API documentation and their published prices. A custom Connection is any other HTTPS API that accepts a static key; the administrator enters its address and where the key goes.

A Person is your Microsoft work identity within the organization. A grant lets one Person use one whole Connection: whatever the service allows its key to do, apart from requests the Connection blocks. Seeing a service on the website does not mean that every employee can use it.

A Connection token is the short-lived credential your agent receives when it opens a Connection. It lasts 15 minutes and works only for you and that one Connection. Maatriks checks your access again on every request made with it.

A blocked request rule refuses requests to a Connection that match a method and path pattern, even for people who have access.

Set up your organization

Organization setup is assisted. The organization must be provisioned with its Microsoft tenant and first administrator before ordinary use. There is no self-service organization signup or employee invitation workflow in this version.

1. Open your service address and choose Console sign-in.

2. Choose Sign in with Microsoft and use the provisioned administrator's work account. Check the organization and signed-in identity shown in the Console.

3. Add a Connection for each service the company wants to use.

4. Have the employee connect their agent and complete Microsoft sign-in. They appear in People after their first successful MCP connection.

5. Open that Person and switch on the Connections they should use. Have the employee's agent list its Maatriks Connections again.

The Console has five main destinations: Connections, People, Logs, API keys and Projects. Administrator status does not automatically grant employee agent access. An administrator who also uses Maatriks through an agent needs Connection access like anyone else.

Add and manage Connections

In Connections, choose Add connection and pick the service. For a preconfigured service, enter a recognizable Connection name and paste that account's complete API key. For example, “Marketing speech” is easier to distinguish than “New key.” Names can contain up to 80 characters.

Before storing a preconfigured key, Maatriks makes one read-only request with it, such as listing OpenAI models. If the service refuses the key, the Console shows The key was not accepted. and nothing is stored.

Choose Custom API for another HTTPS service that authenticates with a static key, then complete these fields from the service's own API documentation:

• Base URL is the address every request starts from, such as https://api.example.com/v2. It must use HTTPS on the standard port and a public host name. Addresses containing a user name, query, fragment, IP address or internal host name are refused.

• Key location is either Header, with a Header name and an optional Value prefix (Authorization and Bearer by default), or Query parameter, with its Parameter name.

• Documentation URL is optional but recommended. Agents read it to learn which requests the service accepts.

• Check path is an optional read-only GET path, such as /me. When you enter one, Maatriks tries it with the key before storing the Connection. Without it, the key is stored without a test request.

The address and key placement are sealed together with the key, so they cannot later point the key somewhere else. To change either, replace the credential and enter the details again.

Keep the key in the key field. Do not put it in a Connection name, a prompt, a support message or an agent's configuration. The Console does not provide a way to reveal the stored key later.

Every person with access can make any request the key allows, apart from blocked requests. Where the service supports it, create a key with only the permissions your company needs. For Gemini, use an API key from a Google project with active billing.

Use Check connection when you need to revalidate the stored key. It repeats the read-only request, using the Check path for a custom Connection. It does not prove remaining credit or that the service will accept every later request.

Open a Connection's Manage menu to:

• Rename it when its purpose changes.

• Replace credential when you rotate the key or, for a custom Connection, change its address or key placement.

• Disconnect it when the company should stop using it. People and API keys lose access through it and new requests are refused. It does not close the account at the service. Adding another Connection later requires setting the intended access again.

If a Connection needs attention, inspect its message and check the provider account or credential. Refresh the Console after another administrator makes a change. A refused or stale change should be reviewed against the current state before repeating it.

Block requests

Expand a Connection to see Blocked requests. Each rule is a method and a path pattern, shown as METHOD /path. A request that matches a rule is refused before it reaches the service, and the agent receives request_blocked with the matched rule.

Preconfigured Connections start with one rule that blocks every DELETE request. You may remove it or add others. Custom Connections start without rules. Separately, Maatriks always refuses the preconfigured services' key-management and account-administration endpoints; these built-in refusals are not listed as rules.

To add a rule, choose a Method (Any, GET, POST, PUT, PATCH or DELETE), enter a Path pattern and add it. Remove deletes a rule.

• A pattern starts with / and is compared with the service's own path, after the Base URL's path and before any query string.

• * matches any text within one path segment, so /v1/files/* matches /v1/files/abc but not /v1/files/abc/content.

• A final /** matches everything below it, so /v1/fine_tuning/** covers every fine-tuning request under that path.

• Everything else is literal. Upper and lower case count as the same, so a rule also covers a differently capitalised path.

Rules judge the request method and path. A service that lets a request body choose a different method (for example a _method form field) is judged by the method actually sent. For the strongest limits, also restrict the key itself at the provider.

Rules only restrict access. They apply to everyone who calls the Connection, including organization API keys and Development projects, from the next request onwards. Changes are recorded in Admin changes.

Manage People and access

Use People to search by name or email and open a Person. Under Connections, one switch per Connection controls whether that Person's agent may use it. Turn on only the Connections the person needs. A Connection's expansion also lists People with the same switches.

A change applies to the person's next request. Switching access off refuses later requests, including those made with a token their agent already holds. Ask the employee's agent to list its Connections again after a change; if their client still shows older information, refresh or reconnect its Maatriks connection.

Development separately enables a personal remote project. In the Person's expansion, turn on Remote development to grant access. It starts off and does not change Connection or API-key permissions. Turning it off blocks new project work and closes runtime and preview access; the Console reports while the environment is stopping.

Person actions have different effects:

• Disable stops that person's Maatriks access, including requests with tokens their agent already holds. Retained access settings and governance evidence remain.

• Reactivate restores the ability to use previously configured access. The role stays the same. Review the retained grants before reactivating someone.

• Promote to administrator allows the person to sign in to the Console and administer the organization.

• Demote to employee ends Console administration while leaving the person's Connection access unchanged.

Maatriks refuses a change that would remove the final active administrator. Promote another appropriate person first if you need to make that change. Changing your own administration access can return you to sign-in immediately.

Connect your agent

MCP, the Model Context Protocol, is the connection that lets your agent list your Maatriks Connections and open them. Use your company's Maatriks address and your Microsoft work identity. You do not need the company's API keys.

Configure Codex from a terminal:

codex mcp add maatriks --url https://maatriks.ai/mcp
codex mcp login maatriks

Complete the browser sign-in with the intended Microsoft work account. If the server is already configured with the correct address, use the login command without adding it again. maatriks is the local server name in these examples; use the name already configured if your administrator chose another one.

Check the configuration with:

codex mcp list

In the Codex terminal interface, /mcp shows active MCP servers. Codex clients on the same host share their MCP configuration. Refer to the official Codex MCP documentation for client-specific configuration options.

Other agents that support remote MCP servers with browser sign-in use the same address, https://maatriks.ai/mcp, typically as a custom connector. Codex, Claude Code, claude.ai and ChatGPT have completed Maatriks sign-in on staging; other clients require compatibility verification.

Your agent calls services from the environment where it runs code. If that environment restricts network access, allow the domain maatriks.ai in its network settings. In hosted assistants such as claude.ai and ChatGPT this is part of the code execution or sandbox settings, which a workspace owner may control. Maatriks cannot change these settings for you.

Start with this request:

List the Maatriks Connections available to me. Do not call any yet.

An empty list can mean that sign-in worked but your administrator has not granted any Connection yet. Ask them to locate you in People and switch on the Connections you need. It is not a reason to copy an administrator's key or use another person's account.

Call a Connection from your agent

Your agent works in three steps. It lists your Connections with list_connections, which returns each Connection's name, service, address to call, documentation link and blocked requests. It opens one with open_connection, which returns a token and its expiry. It then sends the service's own HTTP requests to that address from its sandbox, with the token as a Bearer credential:

curl https://maatriks.ai/api/providers/<connection>/v1/models \
  -H "Authorization: Bearer $MAATRIKS_TOKEN"

Maatriks checks the token, your current access and the Connection's blocked requests, adds the company key privately and streams the service's response back as the service sent it. Methods, JSON, file uploads and binary or streamed responses work as the service defines them. For preconfigured services, the service's usual key header, such as x-api-key for Anthropic, also accepts the token, so official SDKs work with the Connection address as their base URL.

You rarely need these details. Describe the task in ordinary language, for example:

Use my Maatriks OpenAI Connection to transcribe voice-note.wav, then summarize it in three bullet points.

Files and generated media travel directly between your agent's environment and the service through Maatriks; Maatriks does not store them. Save any output you need in your own environment. A link the service returns to its own storage follows that service's rules.

Every request can spend company credit at the service. Be clear about the work you want and avoid asking the agent to try several services unless you intend those separate calls. Maatriks never retries a request automatically. After a timeout or lost response, check the service's returned job or resource before sending the request again.

A token expires 15 minutes after it was opened. The agent can open the same Connection again at any time and continue with the new token.

Preconfigured services

For these services, Maatriks supplies the destination, key placement, documentation link and pricing. Paths below the Connection's address are the service's own, as listed in its API reference.

Direct-session credential creation, key-management and account-administration endpoints, WebSocket and WebRTC are unavailable through Maatriks. An available HTTP path does not mean that every provider operation or SDK transport has been qualified.

Use the developer API

The developer API connects your own application to a named company Connection using native provider SDKs or HTTP, through the same Maatriks address your agent uses. Open API keys in the administrator Console sidebar. Each key has its own Connection permissions and can be shared among people or applications. A person's own Connection access is separate.

1. An administrator chooses Create key, enters a name, and switches on the exact company Connections the key should use. All switches start off; a key with no enabled Connection cannot call a service.
2. Copy the new key once and store it in your application's secret environment as MAATRIKS_API_KEY. The key cannot be displayed again. An administrator can share this same key with the people or applications intended to have its access.
3. Open the key to inspect its Connection permissions. For an enabled Connection, copy its API address and use the provider-specific configuration example. OpenAI SDKs need the displayed /v1 suffix; other providers follow their own example.
4. Run a small read request first. Choose generation, uploads and other paid or state-changing operations deliberately.

Use the Maatriks key in Bearer authentication or, for a preconfigured service, its native key header shown under Preconfigured services. Do not put the key in a URL or send conflicting authentication headers. The company's provider key remains with Maatriks, and the Connection's blocked requests apply.

People sharing a Connection share the resources available to its key, including deleting files or jobs unless a rule blocks it. Provider files follow the provider's retention. No model, Connection or provider is silently substituted.

Maatriks never retries a native API submission automatically. Disable SDK retries when a repeated request could charge or create another resource. After a timeout or interrupted response, inspect the provider's returned job or resource identifier when available before submitting again. Revoking a key or switching off its Connection blocks new Maatriks requests; provider work already accepted may continue, and already-issued signed storage links keep their provider-defined lifetime.

An administrator can open any organization key in API keys and change its Connection switches. The saved change affects that key's new requests without changing other keys or anyone's personal access. Disabling or demoting the creator does not revoke a shared key; revoke the key to stop all of its holders.

Revoke an unused or exposed key from API keys. A lost key must be replaced. If creation was interrupted, refresh the list and revoke any newly created key whose secret you did not receive before creating another. A shared key's requests appear in Logs → Usage under that key; they do not identify which person used it.

Develop a project with your agent

The Stage 1 Development pilot lets your agent build, test, and run an app in your own isolated virtual machine (VM). Git, JavaScript with Node.js and its package tools, and Python with pip are already installed. Your computer does not need to run the app.

1. Ask your administrator to open People, select you, and turn on Remote development under Development.
2. Ask your connected agent to use develop_project, read its current help, and create or open your project. The same tool lets it write files, install dependencies, run tests, read command output, and start your app's development server.
3. Open Projects in Maatriks with the same work account. Select the project and choose Open live preview once your agent has registered the app's port. The live app opens in a separate browser tab that requires your access while you keep working with your agent.

Stop project stops the VM and keeps its files. Starting it again preserves your code and installed project dependencies; ask your agent to restart the app. The VM stops after 30 minutes without new owner work or opening the preview, and after four hours unless you deliberately reopen it through your agent. Reading status does not keep it running. If a response is lost, have the agent check the same operation instead of repeating the command. If startup needs attention, ask your administrator to arrange operator recovery. Stop and Delete remain unavailable until that startup is resolved.

To keep a source copy, have your agent finish or cancel every command and the app server, then choose Export source while the VM stays running. Exports are limited to 256 MiB and 10,000 files; download within 24 hours while the VM is running. Delete project permanently removes that project's data after explicit confirmation.

Each person can have one project. Across all organizations, the shared pilot allows four retained projects and one active VM, with 32 GiB of storage per project. An unresolved startup keeps that capacity reserved until operator recovery. A project exposes one app port. Preview supports secure __Host- cookies; ordinary cookie names are not supported. SSH and administrator access inside the VM are unavailable. Managed project credentials and integrations, public publishing, and team sharing are deferred; this is a personal development environment.

Limits and retention

The service you call applies its own limits in addition to these. Its error responses pass through unchanged.

MiB and GiB are binary size units. Expired Connection tokens are removed by daily maintenance 24 hours after they expire. Usage and Admin-change records do not contain prompts, request or response content, file bytes, keys or tokens.

These Maatriks periods do not describe retention in your agent's conversation, its sandbox, downloaded copies, or the service's systems. See the Privacy policy for those data boundaries.

Review Logs and provider usage

In Logs, choose Usage for requests through Connections or Admin changes for recorded administration. The default view covers seven days. Times and date filters use UTC. Change the range and choose Apply filters; use Older entries to continue through results.

Usage covers every caller: a person's agent, an organization API key or a Development project. It can be filtered by caller, Connection and outcome. Each record shows the caller, Connection, method, a redacted endpoint, status, transferred size and duration. The redacted endpoint replaces path segments that look like identifiers, such as those containing digits, @, = or : or longer than 32 characters, with {id}, and never includes the query string.

For preconfigured services, cost details show available estimates, quantities, pricing date and calculation basis. Estimates use published rates before account discounts, allowances, taxes and billing adjustments. Jutusta credits are shown separately when its account-specific currency rate is unknown. Missing prices or usage show unavailable cost. Custom Connections show no cost. Use the service's own account for billing reconciliation. An interrupted request can have a cost even when no usage measurement was returned.

Admin changes lets you filter by actor, affected object, change type, and outcome, including Connection, grant and blocked-request changes. Open details to inspect the recorded change. Some display names are current labels; the detail distinguishes these from retained before-and-after facts.

Logs are governance evidence rather than a prompt or output archive. They do not provide an administrator route to read employee content, replay work, export a report, or change retention. An admission refusal does not invent an accepted Usage record.

Troubleshooting

Sign-in succeeds, but the Connection list is empty. Ask your administrator to find your Person and switch on a connected Connection. List again after the correction. Check that you signed in to the intended work account and organization.

A Person is missing from the directory. They appear after the first successful MCP connection. Completing Console sign-in with an employee account is not the onboarding path. Have them finish the agent connection and Microsoft sign-in first.

Your agent asks to authenticate again. In Codex, run codex mcp login maatriks, or use your configured server name, and complete work-account sign-in. In other clients, reconnect Maatriks from their connector settings. Reauthentication does not authorize rerunning an uncertain earlier request.

The agent looks for discover_capabilities or cannot find list_connections. Your client kept the tool list from before September 26. Refresh the Maatriks connector's tools in its settings, or reconnect it, and start a new conversation.

The agent hesitates to use the token. The token from open_connection is a 15-minute Maatriks token for one Connection, not the service's key; Maatriks adds the key on its own servers. Using it from the agent's sandbox is the intended flow.

The agent cannot reach maatriks.ai. Allow the domain in the network settings of the environment where your agent runs code, as described in Connect your agent. Some hosted clients have been reported not to apply added domains reliably; if the setting is correct and requests still cannot connect, try an agent that runs on your own computer.

The request returns token_expired or invalid_token. Tokens last 15 minutes. Ask the agent to open the Connection again and repeat the request with the new token.

The request returns request_blocked. The Connection blocks that method and path; the response names the matching rule. Ask your administrator if you need the request. Do not work around it through another Connection.

The request returns connection_not_granted, person_inactive or session_ended. Your access changed or your Maatriks session was signed out. List your Connections again, sign in again if asked, and ask your administrator if the Connection should still be available.

The request returns connection_unavailable. The Connection was disconnected or needs attention. Ask your administrator to check it.

The request returns too_many_requests. You already have 16 requests running. Wait for them to finish before starting more.

The request returns request_too_large or timeout. The request exceeded the size or duration limits above. Use a smaller file or the service's own asynchronous job API where it offers one.

The service rejects a request. Errors that do not come from Maatriks are the service's own and pass through unchanged. Check the request against the service's documentation, then ask the administrator to check billing, credit and the key's permissions. Connection Check did not promise that every request would succeed.

The outcome is uncertain. Check the service's returned job or resource, or ask the administrator to inspect Usage. Do not assume failure means no cost, and do not automatically send the work again.

Support needs a reference. Share the safe error code, correlation reference, approximate time, and Connection name with your administrator or info@maatriks.ai. Do not include an API key, Connection token, login token, prompt, or private file unless the receiving process specifically requires and protects it.

Tool reference

Most people can ask their agent in ordinary language. For troubleshooting or a more precise request, these are the three Maatriks tool names:

List first, open only the Connection you need, and open it again when its token expires. Keep the difference between checking existing work at the service and starting new work clear throughout a task. For Development, begin with develop_project help and keep its returned operation and process references.