Credential management

How it works

1. An administrator issues a key for one project and gives it a name.
2. Wexa shows the secret once. Nothing can show it again, so you copy it into your program's secret store.
3. The program sends the key on every call, on any of the four surfaces.
4. The list shows each key's name, creator and last use, never its secret.
5. You revoke a key when its program retires, and you replace it by issuing a new one first.

Issue a key

Console: Settings, then Developer access (/settings/developer-access), the API keys tab. The page works on whichever project you have selected, and shows an empty state until you pick one. The old /api-keys address redirects there.

1. Choose Create key.
2. Enter a Name. It is required.
3. Optionally open Data access to limit what the key can read (see narrow what a key reads).
4. Choose Create key again.
5. In the dialog that follows, reveal and reveal and copy the secret, which starts fab_sk_, then choose Done.

API: POST /v1/apikeys. The request names the organization, department and project the key is for, its name, and optionally an explicit list of permissions as grants.

curl -sS -X POST https://fabric.wexa.ai/v1/apikeys \
  -H "Authorization: Bearer $FABRIC_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"org_id":"org_abc","dept_id":"dept_abc","project_id":"proj_abc","name":"nightly-report-job"}'

const res = await fetch('https://fabric.wexa.ai/v1/apikeys', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FABRIC_USER_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    org_id: 'org_abc',
    dept_id: 'dept_abc',
    project_id: 'proj_abc',
    name: 'nightly-report-job',
  }),
})
const result = await res.json()
console.log(result)

import json, os, urllib.request

req = urllib.request.Request(
    "https://fabric.wexa.ai/v1/apikeys",
    data=json.dumps({
        "org_id": "org_abc",
        "dept_id": "dept_abc",
        "project_id": "proj_abc",
        "name": "nightly-report-job",
    }).encode(),
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['FABRIC_USER_TOKEN']}",
        "Content-Type": "application/json",
    },
)
print(json.load(urllib.request.urlopen(req)))

The response is 201 with id, secret, scope, name and the note store this secret now; it is not retrievable again.

Know the rules of issuing

Each of these will bite if you are surprised by it.

• It takes a user's sign-in token, not another API key. A key cannot mint a key.
• You must be an administrator on the target project. Anyone else gets 403 "API key creation requires an admin role on this project". If the token carries no role, the gateway looks up the caller's real role on that project rather than believing the client.
• A name is required. An empty name is refused with 400 name is required. The key's identifier is a random string with no meaning in it, so a nameless key is one you cannot tell from its neighbours in six months.
• The secret is shown exactly once. Nothing can show it afterwards: not the list, not support, not the database. Losing it means issuing a new key.

Know what a key can do

If you request no permissions, the key gets the default set for the role of the person minting it:

• An administrator's key covers the whole tool surface. That is reading the context graph and the documentation, editing the ontology, reading and writing orchestration, running an agent, creating skills, and changing which model the organization runs on.
• Any other role, or a role the gateway does not recognise, falls closed to reading the context graph and reading the documentation. Nothing else.

An explicitly requested list always wins over the default, so a key asked for narrowly stays narrow however senior its minter is. A key can do nothing the person who minted it could not already do.

Two permissions are in no role's default set, because they gate REST planes rather than tools: writing to the data catalog, and pushing local code changes into the code graph. Ask for those explicitly when a program needs them.

Narrow what a key reads

By default a key reads everything its creator can. In the console, Data access lets you limit that with Data clearances (personal data as detail:pii, financial data as detail:financial) and Audiences, which are bare ids such as commercial or part:<id>.

Over the API the same limits go in a data_access field. detail:internal is refused, because no one is ever granted it. See field sensitivity.

List keys

Console: the same API keys tab. The table shows the name, the key identifier, who created it, what data access it has, when it was created, when it was last used (Never if it has not been), and its status, Active or Revoked.

API: GET /v1/apikeys?project_id=…. Secrets are never returned by the list.

Listing needs an administrator on that project, the same check as issuing, with the message 403 "requires an admin role on this project".

Revoke a key

Console: choose Revoke on the key's row and confirm. The dialog warns that revoking is immediate and irreversible, and that anything still calling Wexa with the key stops working right away. A revoked key stays in the list, marked Revoked.

API: DELETE /v1/apikeys/{id}?project_id=…. The project is required and is checked against the key's own scope before anything happens, so an administrator of one project cannot revoke another project's key by guessing its identifier. That returns 404 "no such API key in this project".

Both issuing and revoking write an entry to the audit trail recording who did it, their role, the key and the project. Read lifecycle and audit before you rely on that record, because it says how long those entries survive.

Rotate a key

1. Issue a new key for the same project, naming it so you can tell the two apart. A date in the name is enough.
2. Move the callers over and confirm the new key's Last used column is moving in the list.
3. Revoke the old key. Revoking before step 2 is what turns a rotation into an outage.

There is no rotate action and no automatic expiry: a key stays valid until somebody revokes it. Put a rotation in your own calendar rather than waiting for the product to ask.

Decide who should hold a key

• One key per program, never one per team. Keys are told apart by name and revoked individually, so a key shared by four programs cannot be withdrawn from one of them.
• Name the key after the program that holds it, not after the person who created it. The creator is already recorded in the list. The holder is not recoverable from anywhere else.
• Mint the key from the narrowest account that can do the job. The default permissions follow the minter's role, so an administrator minting a key for a read-only reporting job should request the read permissions explicitly.
• A person does not need a key. People sign in. If someone asks for a key to use by hand, what they want is a project login.
• Revoke on departure, explicitly. Suspending someone's account does not withdraw the keys they issued. Issue and revocation are separate acts, and the keys they minted are recorded against the project.

Use a key

Once issued, the key is what the four surfaces authenticate with: the Wexa MCP server, the REST API and both SDKs. To confirm what a key resolves to, call GET /v1/whoami with it, which returns the caller's identifier, role, scope and grants.

curl -sS https://fabric.wexa.ai/v1/whoami -H "Authorization: Bearer $FABRIC_API_KEY"

import { Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
const result = await fabric.whoami()
console.log(result)

from wexa import Fabric

fabric = Fabric()
result = fabric.whoami()
print(result)

The surface pages cover the header, the environment variable and the client constructor for each. See authentication.

Limits and behavior

Related

• Authentication: the header, environment variable and client constructor each surface uses.
• Usage, quota and billing: the project and organization ceilings that apply on top of a key's own.
• Identity API reference: what GET /v1/whoami returns and how to read it.