Log a Wexa user in with the email and password they use for the console and get an SDK session for one project. The session acts as that user, with their current role, so every call is checked and audited as them. It returns an access token (one hour) and a refresh token (30 days, new on every use). Not on the MCP server: its clients sign in through OAuth.

curl -sS https://fabric.wexa.ai/v1/auth/login \
  -H "content-type: application/json" \
  -d '{"email": "ada@example.com", "password": "'"$FABRIC_PASSWORD"'", "project_id": "6aa9beb7ec8121a43b6c791b"}'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "refresh_token": "fab_srt_Ja2bvA…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "project_id": "6aa9beb7ec8121a43b6c791b",
  "session_id": "sess_Ss5LcvniPbkIkWERMiY8YUAO"
}

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

// Resolves to a ready client; onTokens receives { accessToken, refreshToken, expiresAt }
const fabric = await Fabric.login({
  workspace: 'https://fabric.wexa.ai',
  email: 'ada@example.com',
  password,
  projectId: '6aa9beb7ec8121a43b6c791b',
  onTokens: (tokens) => saveTokens(tokens),
})
const result = await fabric.whoami()

from wexa import Fabric

# Returns a ready client; on_tokens receives {"access_token", "refresh_token", "expires_at"}
fabric = Fabric.login(
    "https://fabric.wexa.ai", "ada@example.com", password,
    "6aa9beb7ec8121a43b6c791b", on_tokens=save_tokens,
)
me = fabric.whoami()

Parameters

Parameter	Type	Required	Notes
`email`	string	Required	The user's Wexa email address.
`password`	string	Required	The user's Wexa password. A wrong email or password is refused (401, `invalid_credentials`); the two cases look the same on purpose.
`project_id`	string	Required	The project the session is locked to. `projectId` in the TypeScript SDK. Must be a project id, or the call is refused (400, `invalid_request`). The user must be a member of it, or the call is refused (403, `forbidden`).
`grants`	string[]	Optional	Narrows the session to fewer grants than the user's role gives, for example `["fabric:query.read"]`. Every grant named must be in the user's role, or the call is refused (400, `invalid_request`).
`workspace`	string	SDK only	Your Wexa deployment's URL.
`onTokens` / `on_tokens`	function	SDK only	Optional callback receiving every new token pair, starting with this one.

Errors

ValidationError (400, invalid_request): the body is not JSON, or email, password or project_id is missing or empty.
ForbiddenError (403): the user is suspended in its organization (account_suspended), or the call came from a browser origin that is not allowed (origin_not_allowed).
QuotaExceeded (429): too many failed logins for this email or address. retry_after / retryAfter says how many seconds to wait.
UpstreamError (502): the account service behind the gateway could not be reached. Retrying later can help.

Show full response

A real response, captured from a live call to login. The tokens are cut short here:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "refresh_token": "fab_srt_Ja2bvA…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "org_id": "6a79a770b6c128ccc24bfca8",
  "project_id": "6aa9beb7ec8121a43b6c791b",
  "session_id": "sess_Ss5LcvniPbkIkWERMiY8YUAO",
  "grants": [
    "fabric:query.read",
    "fabric:docs.read",
    "fabric:ontology.write",
    "fabric:orchestrate.read",
    "fabric:orchestrate.write",
    "fabric:agent.run",
    "fabric:skill.write",
    "fabric:model.write",
    "fabric:model.run",
    "fabric:connector.run",
    "fabric:flow.delete",
    "fabric:kb.delete",
    "fabric:table.read",
    "fabric:table.write"
  ]
}

// Fabric.login resolves to a ready client. onTokens receives the pair:
{
  accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…',
  refreshToken: 'fab_srt_Ja2bvA…',
  expiresAt: 1790253600
}

# Fabric.login returns a ready client. on_tokens receives the pair:
{
 "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
 "refresh_token": "fab_srt_Ja2bvA…",
 "expires_at": 1790253600.0
}

expires_at is the access token's expiry in seconds since the epoch. whoami on the new client reports auth_kind: "session" and the session_id.

More details

Use an API key when a service calls Wexa as itself; use login when you build your own login page on top of Wexa. Both SDKs keep the token pair in memory, refresh the access token before it runs out, and hand you every new pair so you can save it. See refresh-session and logout.

In a browser, login and every later call work only from origins your project admin lists under Developer access → Allowed origins in the console. Calls from a server are not affected.

An unverified email can log in for seven days after signup, the same as in the console; after that, login is refused until the email is verified.

ConfigurationError is raised in the SDK before any request when a required option is missing, or when an API key and a token pair were both given.

Not a governed tool: it runs before any tool call. Every call the new session makes afterwards runs through the full lifecycle as the logged-in user.

Resume a saved session

Build the client from the saved pair instead of logging in again. It refreshes on its own when the access token runs out. Over REST there is no client: send the saved access token as the bearer, and when a call comes back 401 with invalid_token, trade the refresh token for a new pair and save it.

curl -sS https://fabric.wexa.ai/v1/whoami \
  -H "authorization: Bearer $FABRIC_ACCESS_TOKEN"

# after a 401 invalid_token: get a new pair, then save both tokens
curl -sS https://fabric.wexa.ai/v1/auth/refresh \
  -H "content-type: application/json" \
  -d '{"refresh_token": "'"$FABRIC_REFRESH_TOKEN"'"}'

const fabric = new Fabric({
  workspace: 'https://fabric.wexa.ai',
  accessToken: saved.accessToken,
  refreshToken: saved.refreshToken,
  onTokens: (tokens) => saveTokens(tokens),
})

fabric = Fabric(
    "https://fabric.wexa.ai",
    access_token=saved["access_token"],
    refresh_token=saved["refresh_token"],
    on_tokens=save_tokens,
)

Ask for less than the role gives

curl -sS https://fabric.wexa.ai/v1/auth/login \
  -H "content-type: application/json" \
  -d '{"email": "ada@example.com", "password": "'"$FABRIC_PASSWORD"'", "project_id": "6aa9beb7ec8121a43b6c791b", "grants": ["fabric:query.read"]}'

const reader = await Fabric.login({
  workspace, email, password, projectId,
  grants: ['fabric:query.read'],
})

reader = Fabric.login(workspace, email, password, project_id,
                      grants=["fabric:query.read"])

Every tool call works the same way: How every tool call works.